Confirm Funds

Overview

The Confirm Funds API is used to check whether the funds for a transaction are still available and can be settled.

The order management system should submit a ConfirmFundsRequest message to determine whether to ship goods. The asynchronous version of this operation returns a ConfirmFundsReply message only when the funds availability reaches an actionable state (for example, Success or Fail).

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 ConfirmFunds API first, with PerformReauthorization set to true wherever applicable. Please 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, contact the customer to make payment with a different payment method.

URI Summary

Action	URI Template	URI Example	Request Content Type	Response Content Type
(Asynchronous) POST	/vM.m/stores/{StoreID}/payments/funds/confirm/async/{TenderType}.xml	/v1.0/stores/TMSUS/payments/funds/async/confirm/async/VC.xml	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 OrderIds 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)	Attribute that indicates whether the payment account number is tokenized	String	true or false
PaymentContext/ EncryptedPaymentAccount UniqueId	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 OrderIds 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	"true" if reauthorization is to be performed in case the funds are unavailable and where applicable. "false" if no reauthorization is to be performed. Omission implies a value of "false". However, it is recommended to set this to true always.	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 - Bank Transfer

<?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>false</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 OrderIds 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)	Attribute that 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 OrderIds across all transactions that the client initiateswith this service.	String	Max 20 characters
FundsAvailable	Yes	This element identifies if the funds are available or not	String	Success or Fail or Timeout
TenderType	Yes	This element identifies the tender type used for the transaction	String	2-4 Characters
ReauthorizationAttempted	Yes	This element identifies 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 - Bank Transfer

<?xml version="1.0" encoding="UTF-8"?>
<ConfirmFundsReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <PaymentContextBase>
        <OrderId>12345</OrderId>
    </PaymentContextBase>
    <FundsAvailable>Success</FundsAvailable>
    <ReauthorizationAttempted>false</ReauthorizationAttempted>
</ConfirmFundsReply>