Payments API

Our API is REST-based. It accepts calls in JavaScript Object Notation (JSON). You can use different programming languages to create the JSON. Our API uses standard HTTP response codes and familiar verbs including:

• GET - To retrieve a resource.

• PUT - to update existing resources.

• PATCH - To update existing resources.

• DELETE - To delete existing resources.

Available endpoints:

• AuthenticateThreeDSecure

• Authorization

• Capture

• Credit

• Iin

• ThreeDSecureVersion2

• VerifyThreeDSecure

• Void

AuthenticateThreeDSecure

Endpoint: /AuthenticateThreeDSecure

Authenticate 3DS Request

A signed POST request used following a call to VerifyThreeDSecure to request an authentication of a customer’s 3DSecure details, and to retrieve the Xid, Cavv and Eci values to include in a subsequence Authorisation request within a Request object.

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) associated with the transaction	String
OrderReference	The unique order reference assigned to the transaction before it was presented to Cashflows	String
Amount	The amount of the transaction	Double
Currency	Currency of payment	String
CardNumber	The full Primary Account Number (PAN) on the card	String
CardToken	The tokenized value for the PAN	String
ExpiryDateMonth	The payment card’s expiry month	String
ExpiryDateYear	The payment card’s expiry year as two digits	String
MessageId	The MessageId returned in the VerifyThreeDSecure response	String
PaRes	The PaRes element returned from the scheme ACS server	String

Authorization

Endpoint: /Authorisation

Authorisation: request/response information

A signed GET request to the endpoint will return an example request and an example response within a Request object.

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) to send the transaction to - Required	String
OrderReference	The unique reference assigned to the transaction before it was presented to Cashflows - Required	String
ParentTransactionId	The original authorisation or verify reference. Required if the PaymentType is RecurringPayment and/or UsingStoredCredentials is True	String
SchemeTransactionId	The ‘Trace ID’ for Mastercard transactions or the ‘Transaction Identifier’ for Visa transactions.	String
Amount	The amount of the transaction	Double
Currency	Currency being used for transaction - Required	String
Description	The description to apply to the transaction	String
CardHolderName	The name on the payment card	String
CardHolderAddress1	The first line of the payment card’s billing address.	String
CardHolderAddress2	The second line of the payment card’s billing address	String
CardHolderCity	The city of the payment card billing address.	String
CardHolderState	The state of the payment card billing address.	String
CardHolderPostcode	The post-code/zipcode of the payment card billing address.	String
CardHolderCountry	The country of the payment card billing address in two letter ISO format.	String
CardHolderEmail	The email address of the card holder.	String
CardHolderTelephone	The phone number of the card holder	String
CardHolderIpAddress	The IP Address from which the card holder initiated the transaction.	String
CardNumber	The full Primary Account Number (PAN) on the card. Mandatory unless providing CardToken or UsingStoredCredentials is True	String
CardToken	The tokenized value for the PAN. Mandatory unless providing CardNumber or UsingStoredCredentials is True	String
ReturnToken	Indicates that the response will return a tokenized PAN if response status successful	Boolean
Cvv	The three- or four-digit security code from payment card. Mandatory unless UsingStoredCredentials is True	String
ExpiryDateMonth	The payment card’s expiry month. Mandatory unless UsingStoredCredentials is True	String
ExpiryDateYear	The payment card’s expiry year as two digits. Mandatory unless UsingStoredCredentials is True.	String
StartDateMonth	The payment card’s start month where provided	String
StartDateYear	The payment card’s start year as two digits, where provided	String
IssueNumber	The issue number of the payment card, where provided	String
Is3Ds	Indicates that the merchant is providing 3DSecure details themselves. If True, Xid, Cavv and Eci must be provided.	Boolean
Ewallet	Indicates a transaction has been processed using one of ‘The Pays’ (Applepay, Googlepay, Samsungpay etc).	Boolean
EwalletType	The EwalletTypes supported by the API. Valid values: ApplePay GooglePay SamsungPay Other	String
ScaExemptionIndicator	Strong Customer Authentication Exemption Indicator: reason of exemption to be sent to the schemes. Valid Values MerchantInitiated LowRisk Recurring LowValue ScaDelegation SecureCorporatePayment	String
ThreeDSecureData	3DSecure authorisation data	Object
ThreeDSecureData.Xid	3DSecure Transaction Id	String
ThreeDSecureData.Cavv	3DSecure Cardholder Authentication Verification Value	String
ThreeDSecureData.Eci	3DSecure Electronic Commerce Indicator	String
ThreeDSecureData.ThreeDSecureVersion	States which ‘3D Secure Protocol’ (ThreeDSecureVersion) was used in the cardholder authentication	String
ThreeDSecureData.DSTransId	Directory Server Transaction ID given to a transaction following a 3D Secure Cardholder Authentication	String
Mcc6012Data	Must be provided if the MCC code of the MID is 6012, 6051 or 7299	Object
Mcc6012Data.PrimaryAccountNumber	Customer’s account number. For PAN numbers use first 6 and last 4 digits	String
Mcc6012Data.Lastname	Lastname of the cardholder	String
Mcc6012Data.DateOfBirth	Cardholder’s date of birth	String
Mcc6012Data.Postcode	Cardholder’s postcode	String
UsingStoredCredentials	Indicates that the transaction is being processed with card data that has been stored. If True then ParentTransactionId and TransactionClass must be supplied. Should not be sent for payment type Auth or Payment	Boolean
Descriptor	The characters to be appended to the DBA name (statement narrative) displayed on the cardholder’s statement	String
PaymentType	The types of payment supported by the API, valid values: Auth Payment RecurringPayment Verify RecurringAuth - Required	String
TransactionClass	The channel through which the transaction was accepted. If not supplied, then ecom is assumed	String
RecurrenceType	Used to override the default setting on the MID specified	String

Authorisation Request

The Authorisation command allows you to make a POST request to authorisation and payment requests (both one-off and recurring), and also card verification requests within a Request object.

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) to send the transaction to - Required	String
OrderReference	The unique reference assigned to the transaction before it was presented to Cashflows - Required	String
ParentTransactionId	The original authorisation or verify reference. Required if the PaymentType is RecurringPayment and/or UsingStoredCredentials is True	String
SchemeTransactionId	The ‘Trace ID’ for Mastercard transactions or the ‘Transaction Identifier’ for Visa transactions.	String
Amount	The amount of the transaction	Double
Currency	Currency being used for transaction - Required	String
Description	The description to apply to the transaction	String
CardHolderName	The name on the payment card	String
CardHolderAddress1	The first line of the payment card’s billing address.	String
CardHolderAddress2	The second line of the payment card’s billing address	String
CardHolderCity	The city of the payment card billing address.	String
CardHolderState	The state of the payment card billing address.	String
CardHolderPostcode	The post-code/zipcode of the payment card billing address.	String
CardHolderCountry	The country of the payment card billing address in two letter ISO format.	String
CardHolderEmail	The email address of the card holder.	String
CardHolderTelephone	The phone number of the card holder	String
CardHolderIpAddress	The IP Address from which the card holder initiated the transaction.	String
CardNumber	The full Primary Account Number (PAN) on the card. Mandatory unless providing CardToken or UsingStoredCredentials is True	String
CardToken	The tokenized value for the PAN. Mandatory unless providing CardNumber or UsingStoredCredentials is True	String
ReturnToken	Indicates that the response will return a tokenized PAN if response status successful	Boolean
Cvv	The three- or four-digit security code from payment card. Mandatory unless UsingStoredCredentials is True	String
ExpiryDateMonth	The payment card’s expiry month. Mandatory unless UsingStoredCredentials is True	String
ExpiryDateYear	The payment card’s expiry year as two digits. Mandatory unless UsingStoredCredentials is True.	String
StartDateMonth	The payment card’s start month where provided	String
StartDateYear	The payment card’s start year as two digits, where provided	String
IssueNumber	The issue number of the payment card, where provided	String
Is3Ds	Indicates that the merchant is providing 3DSecure details themselves. If True, Xid, Cavv and Eci must be provided.	Boolean
Ewallet	Indicates a transaction has been processed using one of ‘The Pays’ (Applepay, Googlepay, Samsungpay etc).	Boolean
EwalletType	The EwalletTypes supported by the API. Valid values: ApplePay GooglePay SamsungPay Other	String
ScaExemptionIndicator	Strong Customer Authentication Exemption Indicator: reason of exemption to be sent to the schemes. Valid Values MerchantInitiated LowRisk Recurring LowValue ScaDelegation SecureCorporatePayment	String
ThreeDSecureData	3DSecure authorisation data	Object
ThreeDSecureData.Xid	3DSecure Transaction Id	String
ThreeDSecureData.Cavv	3DSecure Cardholder Authentication Verification Value	String
ThreeDSecureData.Eci	3DSecure Electronic Commerce Indicator	String
ThreeDSecureData.ThreeDSecureVersion	States which ‘3D Secure Protocol’ (ThreeDSecureVersion) was used in the cardholder authentication	String
ThreeDSecureData.DSTransId	Directory Server Transaction ID given to a transaction following a 3D Secure Cardholder Authentication	String
Mcc6012Data	Must be provided if the MCC code of the MID is 6012, 6051 or 7299	Object
Mcc6012Data.PrimaryAccountNumber	Customer’s account number. For PAN numbers use first 6 and last 4 digits	String
Mcc6012Data.Lastname	Lastname of the cardholder	String
Mcc6012Data.DateOfBirth	Cardholder’s date of birth	String
Mcc6012Data.Postcode	Cardholder’s postcode	String
UsingStoredCredentials	Indicates that the transaction is being processed with card data that has been stored. If True then ParentTransactionId and TransactionClass must be supplied. Should not be sent for payment type Auth or Payment	Boolean
Descriptor	The characters to be appended to the DBA name (statement narrative) displayed on the cardholder’s statement	String
PaymentType	The types of payment supported by the API, valid values: Auth Payment RecurringPayment Verify RecurringAuth - Required	String
TransactionClass	The channel through which the transaction was accepted. If not supplied, then ecom is assumed	String
RecurrenceType	Used to override the default setting on the MID specified	String

Capture

Endpoint: /Capture

Capture Request

Sending a capture POST request following an Authorisation is necessary to receive money from the cardholder, unless that original authorisation was for a Payment or Recurring payment (these are automatically batched for processing) within a Request object..

Parameters	Description	Type
TransactionId	The Id of the transaction to be captured - Required	String
Amount	The Amount (optional and cannot be more than the amount of the original transaction) - Required	Double

Credit

Endpoint: /Credit

Credit Request

POST request used to get a Credit to the payment card associated with a previous authorisation or payment. If you wish to refund the money taken in a previous authorisation/capture or payment you should use the Refund command .

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) to send the transaction to	String
Amount	The amount of the transaction - Required	Double
Currency	Currency being used for transaction - Required	String
OrderReference	The order reference applied to the originating transaction	String
OriginalTransactionId	The unique ID for the parent transaction as provided in the authorisation, payment or verify response. Mandatory unless providing CardNumber or CardToken	String
CardNumber	The full Primary Account Number (PAN) on the card. Mandatory unless providing CardToken or UsingStoredCredentials is True	String
CardToken	The tokenized value for the PAN. Mandatory unless providing CardNumber or UsingStoredCredentials is True	String
Descriptor	These characters are appended to the DBA name (statement narrative) displayed on the cardholder’s statement	String

Iin

Endpoint: /IinDetails

IIN/BIN look-up Request

A POST request to get details on a card with the provided Issuer Identification Number (IIN) - previously known as Bank Identification Number (BIN) within a Request object..

Parameters	Description	Type
iin	The IIN/BIN to check - Required	String

Refund

Endpoint: /Refund

Refund Request

A POST request for a refund can be sent for a captured authorisation or payment originally secured via the Payments API within a Request object..

Parameters	Description	Type
TransactionId | The unique ID for the transaction to be refunded, as provided in the authorisation, payment or verify response - Required		String
Amount | The amount of the transaction - Required		Double
Descriptor | These characters are appended to the DBA name (statement narrative) displayed on the cardholder’s statement		String

ThreeDSecureVersion2

Endpoint: /ThreeDSecureVersion2/Authenticate

Authenticate 3DS v2 Request

GET request Used to initialise a 3DS Authenticate request within a Request object.

Parameters	Description	Type
ThreeDsVersion	The 3DS version for this request - Required	String
MerchantId	Merchant Identifier (Acquirer MID) to send the transaction to	String
OrderReference	The order reference applied to the originating transaction - Required	String
ServerTransactionId	The 3DS server transaction ID created by the pre-authenticate call	String
TransactionId	Transaction data for a 3DS authentication request	Object
TransactionId.Amount	The amount of the transaction - Required	Double
TransactionId.Date	The date of the transaction - Required	String
TransactionId.Currency	The currency of the transaction - Required	String
TransactionId.ShippingAddress	Address data for a 3DS V2.x authenticate request	Object
TransactionId.ShippingAddress.AddressLine1	Address line 1	String
TransactionId.ShippingAddress.AddressLine2	Address line 2	String
TransactionId.ShippingAddress.AddressLine3	Address line 3	String
TransactionId.ShippingAddress.City	City	String
TransactionId.ShippingAddress.Region	Region, County or State. If provided, must be in ISO3166-2 format code.	String
TransactionId.ShippingAddress.Postcode	Postal or ZIP code	String
TransactionId.ShippingAddress.Country	Country as an ISO-2 code	String
TransactionId.ShippingMethod	3DS 2.x Shipping method type, valid values:  CardholderBillingAddress VerifiedAddress NonBillingAddress ShipToStore DigitalGoods TravelEventsTickets Other	String
TransactionId.ThreeRiIndicator	3DS 2.x Requester authentication indicator type, valid values: RecurringTransaction InstallmentTransaction AddCard MaintainCardInformation AccountVerification SplitDelayedShipment TopUp MailOrder TelephoneOrder WhitelistStatusCheck OtherPayment	String
TransactionId.AuthenticationIndicator	3DS 2.x Requester authentication indicator type, valid values: Payment Recurring Installment AddCard MaintainCard Verify	String
TransactionId.RecurringExpiry	Date after which no further authorisations shall be performed. Applies for recurring or installment transactions.	String
TransactionId.RecurringFrequency	Indicates the minimum number of days between authorisations. Applies to recurring or installment transactions.	Integer
TransactionId.Installments	Indicates the number of installments for the installment transaction.	Integer
CardholderData	Cardholder data for a 3DS 2.x authenticate request - Required	Object
CardholderData.CardholderName	The name of the card holder as it appears on the card - Required	String
CardholderData.CardNumber	The full Primary Account Number (PAN) on the card. Should not be provided with a card token.	String
CardholderData.CardToken	The card token. Should not be provided with a card number.	String
CardholderData.ExpiryDateMonth	The payment card’s expiry month - Required	String
CardholderData.ExpiryDateYear	The payment card’s expiry year as two digits - Required	String
CardholderData.BillingAddress	Address data for a 3DS V2.x authenticate request	Object
CardholderData.BillingAddress.AddressLine1	Address line 1	String
CardholderData.BillingAddress.AddressLine2	Address line 2	String
CardholderData.BillingAddress.AddressLine3	Address line 3	String
CardholderData.BillingAddress.City	City	String
CardholderData.BillingAddress.Region	Region, County or State. If provided, must be in ISO3166-2 format code.	String
CardholderData.BillingAddress.Postcode	Postal or ZIP code	String
CardholderData.BillingAddress.Country	Country as an ISO-2 code	String
CardholderData.CardholderEmail	The cardholder’s email address	String
CardholderData. CardholderHomePhone	The cardholder’s home phone number	String
CardholderData.CardholderMobilePhone	The cardholder’s mobile phone number	String
CardholderData.CardholderWorkPhone	The cardholder’s work phone number	String
CardholderData.AccountAgeIndicator	3DS 2.x Requester AccountAgeIndicator Type - Length of time that the cardholder has had the account with the 3DS Requestor, valid values: NoAccount Created LessThan30Days Between30And60Days MoreThan60Days	String
BrowserData	Browser data for a 3DS authentication request - Required	Object
BrowserData.AcceptHeader	Browser Accept header - Required	String
BrowserData.Language	Browser language as defined in IETF BCP47 - Required	String
BrowserData.JavaEnabled	Java status, valid values: Enabled Disabled NotPresent	String
BrowserData.JavaScriptEnabled	JavaScript status, valid values: Enabled Disabled NotPresent	String
BrowserData.ScreenHeight	Browser screen height in pixels - Required	String
BrowserData.ScreenWidth	Browser screen width in pixels - Required	String
BrowserData.TimeZone	Browser time zone. This should be in minutes relative to UTC. So UTC+01:00 would be -60 - Required	Integer
BrowserData.UserAgent	The entire user agent string - Required	String
BrowserData.IpAddress	Browser IP Address	String
BrowserData.ScreenColorDepth	Browser Screen Color Depth in bits	String
MethodCompleted	A value indicating whether the ACS successfully responded to a MethodUrl POST message. This should be null if no MethodUrl POST was required.	Boolean
ChallengeResultsUrl	The URL to post challenge results to. This will be called by the ACS when the challenge is complete. This POST will contain a results (Rreq) message. - Required	String
ChallengeNotificationUrl	The URL to post challenge notifications to. This will be called by the ACS when the challenge is complete. This will POST contain a challenge results (Creq) message. - Required	String
ChallengeWindowSize	3DS v2.x challenge window size, valid values: Window250X400 Window390X400 Window500X600 Window600X400 FullScreen - Required	String
MessageCategory	Indicates the category of the EMV 3-D Secure message, valid values: Payment NonPayment DataOnly ProductionValidationPaymentAuthentication ProductionValidationNonPayment	String
ChallengeIndicator	3DS 2.x Requester Challenge Indicator type, valid values: NoPreference NoChallengeRequested ChallengeRequestedPreference ChallengeRequestedMandate NoChallengeRequestedRiskAnalysed NoChallengeRequestedDataShareOnly NoChallengeRequestedScaPerformed NoChallengeRequestedWhitelistExemption ChallengeRequestedWhitelistPrompt	String

Challenge Results Response (RRes) Message sent by the 3DS Server to the ACS via the DS to acknowledge receipt of the Results Request message within a Request object.

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) associated with the transaction - ** Required**	String
Rreq	A Results Request (Rreq) object - Required	String
ThreeDsVersion	The 3DS version for this request - Required	String
ResultsStatus	3DS 2.x Challenge Result Status type, valid values:ResultRequestReceived ChallengeRequestNotSent AresNotReceived	String

Pre-Authenticate 3DS Request

Used to initialise a 3DS Pre-Authenticate request within a Request object.

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) associated with the transaction - Required	String
OrderReference	The unique order reference assigned to the transaction before it was presented to Cashflows - Required	String
CardNumber	The full Primary Account Number (PAN) on the card. Should not be provided with a card token	String
CardToken	The card token. Should not be provided with a card number	String
MethodNotificationUrl	The URL to post Method notifications to. If a method POST occurs, then a notification will be POSTed to this URL when the ACS is finished with the method POST. If %%SERVERTRANSACTIONID%% is included in the URL, then this will be substituted with the Server Transaction ID - Required	String

VerifyThreeDSecure

Endpoint: /VerifyThreeDSecure

Verify 3DS Enrolment Request

Used to check whether a customer’s card is enrolled in 3DSecure within a Request object.

Parameters	Description	Type
MerchantId	Merchant Identifier (Acquirer MID) to send the transaction to - Required	String
OrderReference	The unique reference assigned to the transaction before it was presented to CashFlows - Required	String
Amount	The amount of the transaction - Required	Double
Currency	The currency of the transaction - Required	String
CardNumber	The full Primary Account Number (PAN) on the card	String
CardToken	The tokenized value for the PAN	String
ExpiryDateMonth	The payment card’s expiry month - Required	String
ExpiryDateYear	The payment card’s expiry year as two digits - Required	String

Void

Endpoint: /Void

Void Request

POST request used to void an authorisation previously obtained using the Authorisation command within a Request object. The request will be accepted only if the authorisation has NOT been captured.

Parameters	Description	Type
TransactionId	The unique ID for the transaction to be voided - Required	String