API Reference

Welcome to the Cashflows API Reference, this section provides an overview of the Cashflows suite of payment APIs, designed to help businesses securely accept, process, and manage payments across various channels with ease and efficiency.

This page will cover some general concepts useful for integrating with any of our APIs. If you want to see the API references for specific APIs you can look at one of the below:

Cashflows Gateway API

The Cashflows Gateway connects your payment processing system with Cashflows and all the functionality that comes with it.

In-Person Payments

A full, standalone API for PCI-PTS secure payment devices to take secure payments and handle payment complexity.

Payments API

The Payments API enables cardholder not present card payments, supporting 3D Secure authentication and card authorisation.

Remote Authentication

How to connect to the Cashflows Gateway and Cashflows acquirer network using the Remote Authentication API.

Introduction

The Cashflows API suite supports secure payment processing, card authentication, and in-person transactions. The RESTful APIs enable fast, scalable integrations suitable for a wide range of use cases.

Sensitive data and PCI-DSS

The storage of Sensitive Authentication Data (track data and/or CVV2) post-authorisation is prohibited by Visa and Mastercard, as well as Requirement 3 of the Payment Card Industry Data Security Standard (PCI-DSS).

If you handle card data you need to demonstrate your systems handle this data securely and that you take full responsibility for your PCI compliance. This includes, but is not limited to, providing your current Attestation of Compliance certificate and evidence of a recent clean vulnerability scan.

A list of approved Security Assessors can be found at: https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors.

Prerequisites

Depend on the method of integration, you will need to gather specific information before being able to connect with Cashflows:

A Cashflows Merchant Account (if you don’t have an account, contact us now )
Account credentials
- Cashflows Gateway - ConfigurationId and API key
- Remote Auth - auth_id and auth_pass
IP Whitelisting (account dependant)

Authentication

The Cashflows API uses a range of authentication mechanisms depending on the product you are using (Gateway API or Remote Auth) to authenticate every request.

Gateway Authentication

Before authenticating you’ll need:

The correct user permissions
Gather your API credentials
Generate your signature

You need different credentials for the integration and production environments, to create an integration account for testing purposes contact implementations@cashflows.com.

User permissions

Before integrating you need to have access to Cashflows Portal. You’ll need the Owner or External Developer user role to access the required pages. If you don’t have access to any of the pages mentioned below, contact your administrator to check your user permissions. If you have not yet set up a Cashflows account, contact us now.

API credentials

To integrate with Cashflows you’ll first need to collect your API credentials:

Configuration ID - unique identifier for your account included in API messages
Current API key - the key for encrypting API messages sent to us

To retrieve your credentials:

Sign into Cashflows Portal and select Configuration from the menu.
Select the API Data tab, the API Data page displays your API configuration details:

If you need to generate a new API key this can be done from the API Data tab:

Select Generate a new API key to generate a new key.
Wherever your integration uses the API key, replace the old key with the new one.
When you have successfully updated all API key references, check the confirmation box and select Update API Key:

Generate your Gateway API signature

As with all API calls you will need to send a request signature with any requests.

To ensure server to server messages have been issued by valid users, request messages must be signed. The Hash field is a SHA2-512 hash calculated by concatenating your security token with a string of the request object. If you don’t have your security token please contact your Implementation Manager.

If the signature is incorrect, an error will be returned. Repeated failures will lock your account, if this happens, please contact your Implementation Manager.

SHA2-512 hash of your request. To generate your hash, concatenate the message body of your request to the API key to give one long string.

Warning

Whitespace and new lines in the request object are included in the hash calculation. We use CR-LF for line breaks, however Unix systems often use just LF, and this can affect calculations. If you can’t match signatures but have the correct password hash, remove unnecessary whitespace from your Request nodes.

After applying a SHA2-512 hash, the concatenated string would look like:

3CDF192F6AC67E3A491EF2B60EA9A03C6B408056CE19C3BBC307EB06A4CE1F4081B8D 021B1E9760E7CC18EED479EDBAFF926DADC2953B5F8B25717B8D5CB7609

Finally, add the generated key as the Hash value in your request:

{
    "ConfigurationID": "12345678-ABCD-ABCD-ABCD-12345678ABCD",
    "Hash": "3CDF192F6AC67E3A491EF2B60EA9A03C6B408056CE19C3BBC307EB06A4CE1F4081B8D021B1E9760E7CC18EED479EDBAFF926DADC2953B5F8B25717B8D5CB7609",
    "Request": {
        "type": "Payment",
        "paymentMethodsToUse": ["creditcard"],
        "parameters": {
            "cardNumber":"4000000000000002",
            "cardCvc": "123",
            "cardExpiryMonth": "05",
            "cardExpiryYear": "23"
        },
        "order": {
            "orderNumber": "Payment ref D1"
        },
        "currency": "GBP",
        "amountToCollect": "10.00"
    },
}

Making Authenticated API Requests

Include the following headers in every API request for Gateway API:

Header	Description
`ConfigurationId`	Identifies your business configuration
`Hash`	SHA-512 hash of the request body + API Key (hex string)

HTTP Header Format

Header	Description
`ConfigurationId`	23001234567890
`Hash`	a9f83c91f2b63a8de9c88a9e3a719d5b23fa2d66e41c0a5d830fcbf6ee1b2a9d7 c9c1a8e93a3e2b5b9c77a8d5e9f2e1a

Cashflows Gateway Warnings

Warning	Description
`UnexpectedPaymentStatus`	Payment has an unexpected status.
`MaximunNumberOfTokensReached`	The maximum number of stored tokens for a customer has been reached
`PaymentPageReferenceDoesNotExist`	Supplied payment page reference does not exists

Cashflows Gateway Error Responses

Error	Description
`CannotRecurOnNonRecurringParent`	Cannot recur on a non recurring parent.
`CaptureAmountExceedsOriginalAuthorisation`	The total capture amount exceeds original authorised amount.
`GenericRejectionOfPayment`	Payment has been refused.
`GenericRejectionOfRefund`	Refund has been refused.
`GenericRejectionOfCredit`	Credit payment has been refused.
`InvalidCaptureStatus`	Capture has an invalid status.
`InvalidPaymentForRefund`	Unable to refund this payment.
`InvalidPaymentForCredit`	Unable to perform credit payment.
`InvalidPaymentStatus`	Payment has an invalid status.
`InvalidRefundStatus`	Refund has an invalid status.
`NonThreeDSecureNotAllowed`	Card payments without 3D Secure are not allowed.
`NoPaymentMethodSelected`	No payment method selected.
`OrderNumberNotUnique`	The supplied order reference is not unique.
`PaymentAlreadyFullyRefunded`	Payment has already been fully refunded.
`PaymentJobAlreadyFinal`	Payment job is already final.
`PaymentJobCanNotBeCancelled`	Payment job can not be cancelled.
`PaymentMethodCommunicationFailure`	Error while communicating.
`PaymentMethodNotAllowed`	Payment method not allowed.
`PaymentMethodRejection`	The payment method rejected the request.
`PaymentMethodLimitsExceeded`	Invalid amount for payment method.
`RecipientDetailFieldsFailedValidation`	The validation for recipient detail fields failed.
`RefundAmountExceedsOriginalAmount`	The total refund amount exceeds original paid amount.
`ThreeDSecureFailed`	3DSecure Authentication Failed - Payment cannot proceed.
`ThreeDSecureUnavailable`	3DSecure Authentication Unavailable - Payment cannot proceed.
`ThreeDSecureMethodPostCallbackConflict`	3DSecure Authentication Unavailable - Payment cannot proceed.
`InvalidCustomerReference`	Invalid customer reference provided.
`DirectAcquiringNotAllowed`	Direct card payments are not allowed.
`TooManyAttempts`	Too many attempts.
`SetParentFrameDomainsNotAllowed`	It is not allowed to set parent frame domains for embedding the payment page.
`RejectWithoutPaymentMethods`	Unable to create paymentjob without payment methods available.

Remote Auth Authentication

To authenticate requests to the Cashflows Remote Auth API, you need two credentials:

Profile ID - this is your Merchant ID and it is a 7 digits number
API Key - this is the password found under Remote in your settings

When submitting a request you need to include the following headers in every Remote Auth API request:

Header	Description
`auth_id`	Your profile ID/Merchant Id
`auth_pass`	Authentication password

Testing and going live

You can use our integration environment to test your integration before going live. The integration environment enables you to simulate different payment scenarios without affecting any live data or interacting with external networks.

You need different credentials for the integration and production environments, we can create an integration account for you and a production account was provided when your account was approved. To create an integration account for testing purposes or if you don’t have production details, contact support@cashflows.com.

Base URLS

Product	Production	Integration
Gateway	https://gateway.cashflows.com/api/gateway	https://gateway-int.cashflows.com/api/gateway
Remote Auth	https://secure.cashflows.com/gateway/remote_auth	https://secure-int.cashflows.com/gateway/remote_auth

Test Cards

If you are testing card payments, you need to use a valid card number. Here are some test card numbers that you can use:

`cardNumber` value	Card Type	CVC	Expiry date
`4510400400099005`	Visa - Credit	123	Any future date within 10 years
`4510500400099002`	Visa - Credit	123	Any future date within 10 years
`4510800400099006`	Visa - Credit	123	Any future date within 10 years
`4000000000000002`	Visa - Credit	123	Any future date within 10 years
`8400182600000009`	Visa - Credit	123	Any future date within 10 years
`8400682600000008`	Visa - Debit	123	Any future date within 10 years
`8400682600011005`	Visa - Debit	123	Any future date within 10 years
`5400200400099009`	Mastercard - Credit	123	Any future date within 10 years
`5400300400099007`	Mastercard - Credit	123	Any future date within 10 years
`8500582600000009`	Mastercard - Credit	123	Any future date within 10 years
`5400100400099001`	Mastercard - Debit	123	Any future date within 10 years
`8500182600000008`	Mastercard - Debit	123	Any future date within 10 years
`340000000000009`	American Express - Credit	1234	Any future date within 10 years

Response Codes

Standard HTTP Response Status Codes

HTTP Status Codes for Payment Gateway and Merchant Acquiring APIs

Status Code	Status Text	HTTP Methods (Typical Use)	Description
200	OK	GET, POST, PUT, DELETE	The request has succeeded. Used for successful queries, status updates, or confirmations.
201	Created	POST	A new resource was created (e.g., payment transaction, merchant account, settlement job).
400	Bad Request	Any	Malformed request (e.g., missing parameters, invalid data).
401	Unauthorized	Any	Authentication failed (e.g., invalid API key or token).
403	Forbidden	Any	Authorization refused (e.g., restricted access, insufficient permissions).
404	Not Found	GET, PUT, DELETE	Resource not found (e.g., transaction ID or merchant account doesn’t exist).
500	Internal Server Error	Any	General server-side error (e.g., payment processor failed, unhandled exception).
503	Service Unavailable	Any	Server is temporarily unavailable (e.g., maintenance window, overload).

Acquirer Response Codes - Remote Auth

The Responses consists of a letter followed by a 3-digit code. The last 2 numbers are specific error codes while the first is an internal error code:

A - Authorised
V - Validation error (e.g invalid card number)
D - Declined
R - Referal (treated as declined)
B - blocked
C - cancelled (e.g user pressed cancel on payment page)
S - System error

Code	Reason	Status
Dx01	Non-specific decline	Declined
Dx02	Declined due to funds (insufficient/limit exceeded)	Declined
Dx03	Retain card response	Declined
Dx05	On our blacklist	Declined
Dx07	Live/test mismatch	Declined
Dx08	Refund: Insufficient merchant funds in account	Declined
Dx10	Card authorisation attempt limit reached	Declined
Dx11	Monthly Scheme Decline Rate limit reached	Declined
Dx40	Continuous Authority cancelled for the transaction	Declined
Dx41	Continuous Authorities cancelled for the merchant	Declined
Dx43	Continuous Authorities cancelled for the card	Declined
Dx49	Additional customer authentication required	Declined
Dx90	Pre-Authorisation anti-fraud block	Declined
Dx91	Post-Authorisation anti-fraud block	Declined
Rx01	Not Authorised	Referral
Ex01	Transaction error	Blocked
Cx01	Transaction cancelled	Cancelled
Cx02	Transaction expired	Cancelled
Sx00	Invalid transaction Request	System Error
Sx01	Connection failure	System Error
Sx02	Invalid response	System Error
Sx03	Response timeout	System Error
Sx04	Server error	System Error
Sx05	Server error	System Error
Sx06	No response from issuer	System Error
Sx07	Service not available	System Error
Sx99	Unknown Error	System Error
Vx01	Invalid merchant details	Validation Error
Vx02	Invalid expiry date	Validation Error
Vx03	Invalid start date	Validation Error
Vx04	Invalid issue number	Validation Error
Vx05	Invalid CVV	Validation Error
Vx06	Invalid card number	Validation Error
Vx07	Card holder name not set	Validation Error
Vx08	Insufficient address details	Validation Error
Vx09	Invalid country code	Validation Error
Vx10	Invalid cart ID	Validation Error
Vx11	Invalid email address	Validation Error
Vx12	Invalid phone number	Validation Error
Vx13	Invalid amount	Validation Error
Vx14	Invalid currency code	Validation Error
Vx15	Invalid customer IP	Validation Error
Vx16	Original trans not found	Validation Error
Vx17	Invalid merchant IP	Validation Error
Vx18	Unknown transaction type	Validation Error
Vx19	Card number changed	Validation Error
Vx20	Currency changed	Validation Error
Vx21	Original trans ref required	Validation Error
Vx22	Amount exceeds original	Validation Error
Vx23	Can not refund this type of transaction	Validation Error
Vx24	Amount changed	Validation Error
Vx25	User account details required	Validation Error
Vx26	Invalid request	Validation Error
Vx27	Original trans not pre-auth	Validation Error
Vx28	Transaction mode changed	Validation Error
Vx29	Card/Currency combination not supported	Validation Error
Vx30	Unknown card type	Validation Error
Vx31	Issue number required	Validation Error
Vx32	Issue number not required	Validation Error
Vx33	Duplicate transaction	Validation Error
Vx34	Unable to void transaction	Validation Error
Vx35	Original trans was not authorised	Validation Error
Vx36	Invalid PIN	Validation Error
Vx37	Unknown transaction class	Validation Error
Vx38	Original transaction type does not match	Validation Error
Vx39	Card expired	Validation Error
Vx40	CVV Required	Validation Error
Vx41	Original transaction already settled	Validation Error
Vx42	Original transaction already cancelled	Validation Error
Vx43	This card does not support the required transaction type	Validation Error
Vx44	Transaction details do not match original	Validation Error
Vx48	User Details not valid	Validation Error
Vx52	3DS Not Enabled	Validation Error
Vx53	3DS Data Invalid	Validation Error
Vx54	Concurrent Authorisations	Validation Error
Vx55	Invalid Funds Recipient Date (MCC 6012, 6051 or 7299 merchants)	Validation Error
Vx56	Terminal mismatch	Validation Error
Vx57	Transaction not allowed on this card	Validation Error
Vx58	Original transaction requires 3DS attempt/auth	Validation Error
Vx59	ECOM transactions require 3DS attempt/auth	Validation Error
Vx60	Verify for Amex card not supported	Validation Error
Vx61	Recurrence Flag usage invalid	Validation Error
Vx62	Initial Sale/Verify ARN missing for subsequent sale	Validation Error
Vx63	Initial Sale/Verify for subsequent sale not approved	Validation Error
Vx64	Initial transaction on card expired	Validation Error