Confirm Funds
Overview
The Confirm Funds API is used to check whether the funds for a transaction are still available and can be settled.
For Debit Transactions, Confirm Funds Before Settlement
Any system that calls Radial's Payment Settlement (Debit) API must integrate Radial's Confirm Funds API into the business flow. You must invoke the Confirm Funds API first, with PerformAuthorization set to true, and then invoke debit settlement. Use the original authorization amount in the amount field of the ConfirmFunds request, even if the amount does not match the current shipment cost (debit amount).
If the response to ConfirmFunds API returns FundsAvailable as Fail, this means that there is an issue with the authorization, and the shipment must be withheld from fulfillment. When this occurs, ask the customer to provide payment with a different payment method.
NOTE: When a confirm funds request is sent for the use case of checking a valid authorization before fulfilling the order, please arrange to release the shipment without any further delays. This will help ensure that the authorization is still good when the capture funds request is sent.
URI Summary
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| (Default Synchronous) POST | /vM.m/stores/{StoreID}/payments/funds/confirm/{TenderType}.xml | /v1.0/stores/TMSUS/payments/funds/confirm/VC.xml | application/xml or text/xml | application/xml or text/xml |
| (Asynchronous) POST | /vM.m/stores/{StoreID}/payments/funds/confirm/async/{TenderType}.xml | /v1.0/stores/TMSUS/payments/funds/confirm/async/VC.xml | application/xml or text/xml | 200 + XML response |
Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentContext | Yes - Either PaymentContext or PaymentContextBase must be present. | Unique identifier of the payment transaction for the order. | ComplexType | |
| PaymentContext/ OrderId |
Yes | Unique identifier of the order. The client must ensure uniqueness of OrderId values across all transactions that the client initiates with this service. | String | Max 20 characters |
| PaymentContext/ PaymentAccountUniqueId |
Yes - Either PaymentAccountUniqueId or EncryptedPayment AccountUniqueId must be present. | Either a raw PAN (payment account number such as a credit card number) or a token representing a PAN. | String | Max 22 characters |
| PaymentContext/ PaymentAccountUniqueId/ @isToken |
Yes (when PaymentAccountUniqueId is present) | This attribute indicates whether the payment account number is tokenized. | String | true or false |
|
PaymentContext/ |
Yes - Either PaymentAccountUniqueId or EncryptedPayment AccountUniqueId must be present. | Client-encrypted PAN. Used for clients who use client-side encryption to encrypt credit card numbers in the JavaScript that runs in their browser. For a webstore that is not PCI compliant, this ensures that the webstore never sees raw PANs. | String | Max 1000 characters |
| PaymentContextBase | Yes - Either PaymentContext or PaymentContextBase must be present. | Used for tenders that do not use a PaymentAccountUniqueId. | ComplexType | |
| PaymentContextBase/ OrderId |
Yes | Unique identifier of the order. The client must ensure uniqueness of OrderId values across all transactions that the client initiateswith this service. | String | Max 20 characters |
| Amount | Yes | The amount of funds being checked. | String |
Positive decimal, up to two decimal places (for example, 4.75) |
| Amount/ @currencyCode |
Yes | Type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| PerformReauthorization | No |
Send a value of true if reauthorization is to be performed in case the funds are unavailable and where applicable; or false if no reauthorization is to be performed. Omission implies a value of "false". It is recommended to always set this to true. |
Boolean | true or false |
| requestId | Yes | RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. | String | Up to 40 Characters |
Request Example - Credit Card
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<ConfirmFundsRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
<PaymentContext>
<OrderId>12345</OrderId>
<PaymentAccountUniqueId isToken="false">4111111111111111</PaymentAccountUniqueId>
</PaymentContext>
<Amount currencyCode="USD">23.54</Amount>
<PerformReauthorization>true</PerformReauthorization>
</ConfirmFundsRequest>Request Example - PayPal
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<ConfirmFundsRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
<PaymentContextBase>
<OrderId>12345</OrderId>
</PaymentContextBase>
<Amount currencyCode="USD">23.54</Amount>
<PerformReauthorization>true</PerformReauthorization>
</ConfirmFundsRequest>Response Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentContext | Yes - Either PaymentContext or PaymentContextBase must be present. | Unique identifier of the payment transaction for the order. | ComplexType | |
| PaymentContext/ OrderId |
Yes | Unique identifier of the order. The client must ensure uniqueness of OrderId values across all transactions that the client initiates with this service. | String | Max 20 characters |
| PaymentContext/ PaymentAccountUniqueId |
Yes. | The Payment Service Response will always return a token representing a PAN. | String | Max 22 characters |
| PaymentContext/ PaymentAccountUniqueId/ @isToken |
Yes (when PaymentAccountUniqueId is present) | This attribute indicates whether the payment account number is tokenized. | String | In the the Response object this element will always be true |
| PaymentContextBase |
Yes only if PaymentContext is not present |
Used for tenders that do not use a PaymentAccountUniqueId. | ComplexType | |
| PaymentContextBase/ OrderId |
Yes | Unique identifier of the order. The client must ensure uniqueness of OrderId values across all transactions that the client initiateswith this service. | String | Max 20 characters |
| FundsAvailable | Yes | This element indicates if the funds are available or not. | String | Success, Fail, Pending, or Timeout |
| TenderType | Yes | This element identifies the tender type used for the transaction. | String | 2-4 Characters |
| ReauthorizationAttempted | Yes | This element indicates if a reauthorization was performed or not as part of the confirm funds process. | Boolean | true or false |
| sessionId | No | sessionId globally identifies a request message and is used to protect against duplicate request processing. | String | Up to 40 Characters |
Response Example - Credit Card
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<ConfirmFundsReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>12345</OrderId>
<PaymentAccountUniqueId isToken="true">411111vjOiXS1111</PaymentAccountUniqueId>
</PaymentContext>
<TenderType>VC</TenderType>
<FundsAvailable>Success</FundsAvailable>
<ReauthorizationAttempted>false</ReauthorizationAttempted>
</ConfirmFundsReply>Response Example - PayPal
Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<ConfirmFundsReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContextBase>
<OrderId>12345</OrderId>
</PaymentContextBase>
<TenderType>PY</TenderType>
<FundsAvailable>Success</FundsAvailable>
<ReauthorizationAttempted>false</ReauthorizationAttempted>
</ConfirmFundsReply>