Cashflows Gateway API
Recurring payments
For a recurring payment, your website needs to send us a payment request that includes a unique job number for the parent job under which the recurring child payments will take place. Therefore, you need to first create a parent payment job. Our Cashflows Gateway can then process the payment as usual and reply with a notification webhook to tell you the payment status of the parent job.
Any recurring child payments do not need notification webhooks. The status of a child payment is returned in the API response. Therefore, using the API response saves you some work and avoids unnecessary webhook traffic.
If you have set up a notification webhook in Cashflows Go, it gets used by the parent job (as required) but is also used automatically by the child payment jobs (not required). Therefore, instead of specifying the notification webhooks in Cashflows Go, you need to specify notification webhooks in the create payment job API request for the parent payment. This gives you greater control because you include a notification webhook only when need to (that is in the case of a parent payment). It also means that you don’t need to reply to unnecessary webhooks, as described earlier in How to reply to a notification webhook.
The process for setting up and processing a recurring payment involves the following steps:
1. Create a parent payment job for the initial transaction
The cardholder needs to be present so that they can enter their card details, including security code (CVV) and go through 3-D Secure checks, if applicable. This initial transaction can include a payment or can be for a zero amount (to verify the card). This is also when you specify the notification webhook to use for the status of the parent payment. For information about creating a parent payment job, see How to create a parent payment job.
2. Create the recurring child payment request that includes the unique job number (parentPaymentJobReference) of the parent payment job so that we can retrieve the card details to use for future payments. For information, see How to create a recurring payment job.
How to create a parent payment job
To set up a recurring payment, you need to create the parent payment job to verify a shopper’s card and take a payment. Future recurring payments will be child payment jobs of this parent.
For a parent payment, you also need to specify the notification webhook to use for the status of the parent payment.
You can create a parent payment job via our Cashflows Gateway or via a hosted payment page, if you’re using one. For information about using a hosted payment page, refer to Adding a hosted payment page to a website.
When you create a payment job via the Cashflows Gateway, you need to include some additional information in the request to make this payment job a parent payment job. The request should include the option ‘IsRecurringPaymentJobParent’.
Example request
{"type": "Payment","locale": "en_GB","options": ["IsRecurringPaymentJobParent"], "paymentMethodsToUse": ["creditcard"],"parameters": {"cardNumber":"4000********0002", "cardCvc": "123", "cardExpiryMonth": "05", "cardExpiryYear": "23", "webhookUrl":"https://www.mywebhookurl"
}, "currency": "GBP", "amountToCollect": "0.00"}
In this example, the payment was a zero-amount authorisation.
In Cashflows Go, the transaction will show as a recurring parent payment in the Advanced tab of the Transaction details. For more information, refer to the Cashflows Go Guide (PDF) on our website.
Example response
{
"data": {
"reference": "210221000411041792",
"createDateTimeUtc": "2021-02-22T17:06:06.9100226Z",
"type": "Payment",
"traceReference": "210220104303388672",
"configurationId": "200426117314086912",
"domain": "cashflows.com",
"locale": "en_GB",
"timeZone": "Europe/London",
"orderHistory": [],
"paymentMethodsToUse": [
"Card"
],
"currency": "GBP",
"amountToCollect": "0.00",
"expirationDateTimeUtc": "2021-08-22T17:06:06.9100204Z",
"dueDateTimeUtc": "2021-02-22T17:16:07.510655Z",
"lastUpdateTimeUtc": "2021-02-22T17:06:06.9100242Z",
"lastProcessedTimeUtc": "2021-02-22T17:06:06.9100234Z",
"flags": {
"recurringParent": true,
"direct": true
},
"attributes": {},
"paymentStatus": "Pending",
"payments": [
{
"reference": "210221100327286784",
"createDateTimeUtc": "2021-02-22T17:06:07.0457549Z",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "0.00",
"steps": [
{
"reference": "210221221533560840",
"createDateTimeUtc": "2021-02-22T17:06:07.5108252Z",
"action": "Start",
"paymentMethods": [
"Card"
],
"status": "Pending",
"amountToCollect": "0.00"
}
],
"flags": {},
"attributes": {
"returnUrlSuccess": "https://www.bing.com/?paymentjobref=210221000411041792&paymentref=210221100327286784",
"returnUrlFailed": "https://www.yahoo.co.uk/?paymentjobref=210221000411041792&paymentref=210221100327286784",
"returnUrlCancelled": "https://www.google.co.uk?paymentjobref=210221000411041792&paymentref=210221100327286784&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/210221000411041792",
"type": "application/json"
},
"action": {
"type": "text/html"
},
"documentation": {
"url": "https://gateway-int.cashflows.com/payment-gateway-api/documentation/index.html",
"type": "text/html"
}
}
}
Important: To comply with financial regulations, a payment request from a financial institution needs to include some extra information about the person who is receiving the funds. This includes payment requests for MOTO, parent and recuring transactions. You need to include the extra details in the recipientDetails object. For information, see Additional details required for financial institutions.
How to create a recurring payment job
When you create the child payment job for the recurring payment, you must include the reference to the parent payment job to enable us to retrieve the card details to use for the payment. For information about creating a parent payment job, see How to create a parent payment job.
Our gateway does not currently support scheduling. Therefore, you need to initiate the recurring payment with the required amount at the required time.
Example request
The payment job request must include the parent payment job number for the default card or card selected by the shopper, for example:
{"amountToCollect": "10.00", "currency": "GBP", "locale": "en_GB", "parentPaymentJobReference" : "200721021609123852", "order": {"orderNumber": "Payment 2"}}
Important: To comply with financial regulations, a payment request from a financial institution needs to include some extra information about the person who is receiving the funds. This includes payment requests for MOTO, parent and recuring transactions. You need to include the extra details in the recipientDetails object. For information, see Additional details required for financial institutions.
Example response
The response contains the payment status. There is no need to specify a notification webhook for a recurring child payment job:
{
"data": {
"reference": "200921017221943304",
"createDateTimeUtc": "2020-09-10T14:20:32.5873637Z",
"type": "Payment",
"traceReference": "200920100402698252",
"configurationId": "200426117314086912",
"domain": "cashflows.com",
"locale": "en_GB",
"timeZone": "Europe/London",
"order": {
"orderNumber": "Payment 2",
"createDateTimeUtc": "2020-09-10T14:20:32.5873662Z",
"orderLines": []
},
"orderHistory": [],
"parentPaymentJobReference": "200721021609123852",
"paymentMethodsToUse": [
"Card"
],
"currency": "GBP",
"amountToCollect": "10.00",
"amountCollected": "10.00",
"paidAmount": "10.00",
"paidDateTimeUtc": "2020-09-10T14:20:33.763025Z",
"expirationDateTimeUtc": "2021-03-10T14:20:32.5873618Z",
"lastUpdateTimeUtc": "2020-09-10T14:20:33.7981683Z",
"lastProcessedTimeUtc": "2020-09-10T14:20:32.5873645Z",
"flags": {
"direct": true
},
"attributes": {},
"paymentStatus": "Paid",
"payments": [
{
"reference": "200921100142737416",
"createDateTimeUtc": "2020-09-10T14:20:32.8319012Z",
"paymentMethods": [
"Card"
],
"status": "Paid",
"amountToCollect": "10.00",
"surchargeAmount": "0",
"paidAmount": "10.00",
"steps": [
{
"reference": "200921217196650516",
"createDateTimeUtc": "2020-09-10T14:20:33.762769Z",
"action": "Start",
"paymentMethods": [
"Card"
],
"status": "Paid",
"amountToCollect": "10.00"
}
],
"flags": {},
"attributes": {
"returnUrlSuccess": "https://gateway-int.cashflows.com/payment?ref=4ab07d818100e4880130c8e35d25ea1b4131ec54744e457ba541445578fced03c977295fb58cd009e7944c69e6a8876cc1af0b024b99302aea53b8ca09aafe24",
"returnUrlFailed": "https://gateway-int.cashflows.com/payment?ref=4ab07d818100e4880130c8e35d25ea1b4131ec54744e457ba541445578fced03c977295fb58cd009e7944c69e6a8876cc1af0b024b99302aea53b8ca09aafe24",
"returnUrlCancelled": "https://gateway-int.cashflows.com/payment?ref=4ab07d818100e4880130c8e35d25ea1b4131ec54744e457ba541445578fced03c977295fb58cd009e7944c69e6a8876cc1af0b024b99302aea53b8ca09aafe24&status=cancelled",
"cashFlowsAcquiringDetails": "{\"AuthCode\":\"AUTHOK\",\"Arn\":\"74501870254010013958712\",\"Message\":\"Authorised\",\"Status\":\"Successful\",\"IssuerResponseCode\":\"00\",\"CvvAvsResult\":\"000\",\"AcquirerResponseCode\":\"A\"}",
"paymentMethodTransactionId": "01S00CECA74"
Important: To comply with financial regulations, a payment request from a financial institution needs to include some extra information about the person who is receiving the funds. This includes payment requests for MOTO, parent and recuring transactions. You need to include the extra details in the recipientDetails object. For information, see Additional details required for financial institutions.