Cashflows Gateway API
Securely storing card details
Our Gateway is an ideal way to enable shoppers to securely save details of a card for an online account or for future purchases, if they want to. When they return to your website to buy something, they can use a stored card for a faster checkout. The card details are never revealed at any stage of the payment process. The card details are securely stored in the Cashflows Gateway. We convert the card details to a unique series of randomly-generated numbers (known as a token).
You can use API calls to send us a request for a token and then use the token in future payment requests instead of the card details. For information, see How to request a token.
We then send you the token to use in payment jobs for future transactions that use the same stored card. For subsequent payments by the same shopper, you send us the token and not the stored card details.
Using a token instead of card details
Our Cashflows Gateway can securely store card details so that they are not revealed at any time during the payment process. If a shopper chooses to store their card details on your website, you can send us the card details and ask us to convert them to a unique series of randomly-generated numbers (known as a token). We then validate the card and send you the token to use in payment jobs for future transactions that use the same stored card. For subsequent payments by the same shopper, you send us the token and not the stored card details.
This section explains how to:
· Ask us to create a token from the card details that you send us. For information, see How to request a token.
· Ask us to create a token during a payment. For example, if a shopper wants to pay with a card that they haven’t stored yet (so we haven’t tokenised it yet). For information, see How to request a token during a payment.
· Use a token for a payment instead of the card details. For information, see How to use a token for a payment.
How to request a token
To request a token, you need to tell us the card details that you would like us to convert to a token (tokenise).
Example Request
POST https://gateway-int.cashflows.com/api/gateway/card-tokenisation
{"cardNumber": "4000000000000002", "CardHolderName" : "A Smith", "cardExpiryYear": "21", "cardExpiryMonth": "10", "cardCvc": "123"}
Example Response
{
"data": {
"token": "1000000000030419",
"cardExpiryMonth": "10",
"cardExpiryYear": "21",
"truncatedCardNumber": "400000****0002"
}
}
How to request a token during a payment
If a shopper wants to pay with a card that they haven’t stored yet (so we haven’t tokenised it yet), you can ask us to tokenise it during the payment process. You add the token request to the payment request by including the option GenerateToken.
Example request to generate a token
{"type": "Payment", "paymentMethodsToUse": ["creditcard"],"parameters": {"cardNumber":"4000000000000002", "cardCvc": "123", "cardExpiryMonth": "05", "cardExpiryYear": "23" }, "order": {"orderNumber": "Payment ref D1T"}, "options": ["GenerateToken"], "currency": "GBP", "amountToCollect": "10.00"}
The response provides the result of the 3-D Secure checks and, if the payment passes the 3-D Secure checks, it includes the requested token.
Example response with the link to the 3-D Secure page:
{
"data": {
"reference": "210221000000135192",
"createDateTimeUtc": "2021-02-18T11:17:27.1270204Z",
"type": "Payment",
"traceReference": "210220104756475984",
"configurationId": "200426117314086912",
"domain": "cashflows.com",
"locale": "en_GB",
"timeZone": "Europe/London",
"order": {
"orderNumber": "Payment ref D1T",
"createDateTimeUtc": "2021-02-18T11:17:27.1270232Z",
"orderLines": []
},
"orderHistory": [],
"paymentMethodsToUse": [
"Card"
],
"currency": "GBP",
"amountToCollect": "10.00",
"expirationDateTimeUtc": "2021-08-18T11:17:27.1270185Z",
"dueDateTimeUtc": "2021-02-18T11:27:27.6829616Z",
"lastUpdateTimeUtc": "2021-02-18T11:17:27.1270223Z",
"lastProcessedTimeUtc": "2021-02-18T11:17:27.1270215Z",
"flags": {
"generateToken": true,
"direct": true
},
"attributes": {},
"paymentStatus": "Pending",
"payments": [
{
"reference": "210221100134352924",
"createDateTimeUtc": "2021-02-18T11:17:27.3627718Z",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "10.00",
"surchargeAmount": "0",
"steps": [
{
"reference": "210221221491613700",
"createDateTimeUtc": "2021-02-18T11:17:27.6831162Z",
"action": "Start",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "10.00"
}
],
"flags": {},
"attributes": {
"returnUrlSuccess": "https://www.mywebshop.com/?paymentjobref=210221000000135192&paymentref=210221100134352924&ordernumber=Payment+ref+D1T",
"returnUrlFailed": "https://www.mywebshop.com/?paymentjobref=210221000000135192&paymentref=210221100134352924&ordernumber=Payment+ref+D1T",
"returnUrlCancelled": "https://www.mywebshop.com?paymentjobref=210221000000135192&paymentref=210221100134352924&ordernumber=Payment+ref+D1T&status=cancelled",
"cashFlowsAcquiringDetails": "{\"ThreeDSecureVersion\":\"1.0.2\",\"ThreeDSecureVersionReason\":\"3-D Secure v2 not enabled for this merchant.\"}"
},
"refunds": [],
"captures": []
}
]
},
"links": {
"data": {
"url": "https://gateway-int.cashflows.com/api/gateway/payment-jobs/210221000000135192",
"type": "application/json"
},
"action": {
"type": "text/html"
},
"documentation": {
"url": "https://gateway-int.cashflows.com/payment-gateway-api/documentation/index.html",
"type": "text/html"
}
}
}
Example response with the token
After 3-D Secure checking is complete, the retrieve payment job provides you with the token (highlighted).
{
"data": {
"reference": "210221000000135192",
"createDateTimeUtc": "2021-02-18T11:17:27.127Z",
"type": "Payment",
"traceReference": "210220104756475984",
"configurationId": "200426117314086912",
"domain": "cashflows.com",
"locale": "en_GB",
"timeZone": "Europe/London",
"order": {
"orderNumber": "Payment ref D1T",
"createDateTimeUtc": "2021-02-18T11:17:27.127Z",
"orderLines": []
},
"orderHistory": [],
"paymentMethodsToUse": [
"Card"
],
"currency": "GBP",
"amountToCollect": "10.00",
"amountCollected": "10.00",
"paidAmount": "10.00",
"paidDateTimeUtc": "2021-02-18T11:19:57.773Z",
"expirationDateTimeUtc": "2021-08-18T11:17:27.127Z",
"dueDateTimeUtc": "2021-02-18T11:27:27.682Z",
"lastUpdateTimeUtc": "2021-02-18T11:19:57.811Z",
"lastProcessedTimeUtc": "2021-02-18T11:17:27.127Z",
"flags": {
"generateToken": true,
"direct": true,
"createdOnMapi": true
},
"attributes": {},
"paymentStatus": "Paid",
"payments": [
{
"reference": "210221100134352924",
"createDateTimeUtc": "2021-02-18T11:17:27.362Z",
"paymentMethods": [
"Card"
],
"status": "Paid",
"amountToCollect": "10.00",
"surchargeAmount": "0",
"paidAmount": "10.00",
"steps": [
{
"reference": "210221221491613700",
"createDateTimeUtc": "2021-02-18T11:17:27.683Z",
"action": "Start",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "10.00"
},
{
"reference": "210221221525168132",
"createDateTimeUtc": "2021-02-18T11:19:57.773Z",
"action": "Process",
"paymentMethods": [
"Card"
],
"status": "Paid",
"amountToCollect": "10.00"
}
],
"flags": {},
"attributes": {
"returnUrlSuccess": "https://www.mywebshop.com/?paymentjobref=210221000000135192&paymentref=210221100134352924&ordernumber=Payment+ref+D1T",
"returnUrlFailed": "https://www.mywebshop.com/?paymentjobref=210221000000135192&paymentref=210221100134352924&ordernumber=Payment+ref+D1T",
"returnUrlCancelled": "https://www.mywebshop.com?paymentjobref=210221000000135192&paymentref=210221100134352924&ordernumber=Payment+ref+D1T&status=cancelled",
"cashFlowsAcquiringDetails": "{\"ThreeDSecureVersion\":\"1.0.2\",\"ThreeDSecureVersionReason\":\"3-D Secure v2 not enabled for this merchant.\",\"AuthenticationStatus\":\"Y\",\"Xid\":\"pBoZubEx533uMpLNFjuXU0LMRql=\",\"Cavv\
\":\"aq0zADZ1wIha0IgU3j9FRt0sA2V=\",\"Eci\":\"05\",\"AuthCode\":\"AUTHOK\",\"Arn\":\"74501871049010015672418\",\"Message\":\"Authorised\",\"Status\":\"Successful\",\"IssuerResponseCode\":\"00\",\"CvvAvsResult\":\"200\",\"AcquirerResponseCode\":\"A\",\"TruncatedCardNumber\":\"400000******0002\"}",
"originatingIpAddress": "81.106.197.200, 95.100.156.174, 88.221.51.77",
"originHeader": "https://integration.cashflows.com",
"paymentMethodTransactionId": "01S00DAA6A7",
"token": "1000000000030419"
},
"refunds": [],
"captures": []
}
]
},
"links": {
"data": {
"url": "https://gateway-int.cashflows.com/api/gateway/payment-jobs/210221000000135192?locale=en_GB",
"type": "application/json"
},
"documentation": {
"url": "https://gateway-int.cashflows.com/payment-gateway-api/documentation/index.html",
"type": "text/html"
}
}
}
How to use a token for a payment
When you have received a token, you can use it in a payment request. You just need to replace the cardNumber field with the token field. We then process the payment as usual.
Example request
{"type": "Payment","locale": "en_GB", "paymentMethodsToUse": ["creditcard"],"parameters": {"token":"1000000000030419", "cardCvc": "123", "cardExpiryMonth": "05", "cardExpiryYear": "23" }, "order" : {"orderNumber": "Payment ref D1UT"}, "currency": "GBP", "amountToCollect": "10.00"}
Example response
{
"data": {
"reference": "210221000033689624",
"createDateTimeUtc": "2021-02-18T11:30:38.7419169Z",
"type": "Payment",
"traceReference": "210220104588703828",
"configurationId": "200426117314086912",
"domain": "cashflows.com",
"locale": "en_GB",
"timeZone": "Europe/London",
"order": {
"orderNumber": "Payment ref D1UT",
"createDateTimeUtc": "2021-02-18T11:30:38.741919Z",
"orderLines": []
},
"orderHistory": [],
"paymentMethodsToUse": [
"Card"
],
"currency": "GBP",
"amountToCollect": "10.00",
"expirationDateTimeUtc": "2021-08-18T11:30:38.7419153Z",
"dueDateTimeUtc": "2021-02-18T11:40:39.2516539Z",
"lastUpdateTimeUtc": "2021-02-18T11:30:38.7419183Z",
"lastProcessedTimeUtc": "2021-02-18T11:30:38.7419176Z",
"flags": {
"direct": true
},
"attributes": {},
"paymentStatus": "Pending",
"payments": [
{
"reference": "210221100167907356",
"createDateTimeUtc": "2021-02-18T11:30:38.8874465Z",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "10.00",
"surchargeAmount": "0",
"steps": [
{
"reference": "210221204311875588",
"createDateTimeUtc": "2021-02-18T11:30:39.2518647Z",
"action": "Start",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "10.00"
}
],
"flags": {},
"attributes": {
"returnUrlSuccess": "https://www.mywebshop.com/?paymentjobref=210221000033689624&paymentref=210221100167907356&ordernumber=Payment+ref+D1UT",
"returnUrlFailed": "https://www.mywebshop.com/?paymentjobref=210221000033689624&paymentref=210221100167907356&ordernumber=Payment+ref+D1UT",
"returnUrlCancelled": "https://www.mywebshop.com?paymentjobref=210221000033689624&paymentref=210221100167907356&ordernumber=Payment+ref+D1UT&status=cancelled",
"cashFlowsAcquiringDetails": "{\"ThreeDSecureVersion\":\"1.0.2\",\"ThreeDSecureVersionReason\":\"3-D Secure v2 not enabled for this merchant.\"}"
},
"refunds": [],
"captures": []
}
]
},
"links": {
"data": {
"url": "https://gateway-int.cashflows.com/api/gateway/payment-jobs/210221000033689624",
"type": "application/json"
},
"action": {
"type": "text/html"
},
"documentation": {
"url": "https://gateway-int.cashflows.com/payment-gateway-api/documentation/index.html",
"type": "text/html"
}
}
}