Tutorial: Make a sweeping variable recurring payment
The Variable Recurring Payments product is available as a Beta version. Coverage will be initially limited to UK CMA9 banks for Sweeping use cases and Natwest UK for Non-Sweeping use cases. Check our VRP Coverage page for the latest update.
This tutorial walks through how to create a UK domestic sweeping variable recurring payment with the Natwest Sandbox.
1. Get Institutions
Optional - This step is optional as it is entirely possible to access account data without retrieving the Institution
list,
however it is often required to display a list of supported banks for your customer to choose which bank they would like
to share their data from.
Note: All requests made to the Yapily API require basic authentication.
To display this list, use GET Institutions:
Request:
curl -L -X GET 'https://api.yapily.com/institutions' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
"meta": {
"tracingId": "acbb76db4ab8f4ac7f039d000456c13f",
"count": 1
},
"data": [
{
"id": "modelo-sandbox",
"name": "Modelo Sandbox",
"fullName": "Modelo Sandbox",
"countries": [
{
"displayName": "United Kingdom",
"countryCode2": "GB"
}
],
"environmentType": "SANDBOX",
"credentialsType": "OPEN_BANKING_UK_AUTO",
"media": [
{
"source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
"type": "icon"
},
{
"source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
"type": "logo"
}
],
"features": [
"INITIATE_ACCOUNT_REQUEST",
"ACCOUNT_REQUEST_DETAILS",
"EXISTING_PAYMENTS_DETAILS",
"ACCOUNT_BALANCES",
"CREATE_BULK_PAYMENT",
"ACCOUNT_PERIODIC_PAYMENTS",
"ACCOUNT_STATEMENTS",
"INITIATE_BULK_PAYMENT",
"ACCOUNT_STATEMENT",
"ACCOUNT",
"INITIATE_DOMESTIC_PERIODIC_PAYMENT",
"INITIATE_SINGLE_PAYMENT_SORTCODE",
"ACCOUNT_DIRECT_DEBITS",
"ACCOUNTS",
"ACCOUNT_TRANSACTIONS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_SINGLE_PAYMENT",
"INITIATE_DOMESTIC_SINGLE_PAYMENT",
"ACCOUNT_STATEMENT_FILE",
"CREATE_INTERNATIONAL_SINGLE_PAYMENT",
"IDENTITY",
"CREATE_DOMESTIC_SCHEDULED_PAYMENT",
"INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
"CREATE_SINGLE_PAYMENT_SORTCODE",
"ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
"INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
"PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
"ACCOUNT_SCHEDULED_PAYMENTS",
"CREATE_DOMESTIC_PERIODIC_PAYMENT"
]
}
]
}
-
Each
Institution
returned contains a logo, name, id and a list of supported features. As we want to allow the customer to perform a UK Domestic Sweeping Variable Recurring Payment, we can offer any institution that supports the featureCREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING
. - This information can be leveraged in a third party application to allow the user to select the bank they wish to make the payment from.
-
Once the user selects a bank, the
id
Institution should be stored to use in the next step.
2. Authorisation
After obtaining the institution-id
and confirming that the bank supports the ability to make a domestic sweeping variable recurring payment,
the next step is to generate an authorisation-url
that is used to redirect the user to their chosen bank and to
authorise the payment request.
To do this, execute Create Sweeping Authorisation:
Request:
curl -L -X POST 'https://api.yapily.com/variable-recurring-payments/sweeping/consents' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"applicationUserId": "variable-recurring-payment-tutorial",
"institutionId": "natwest-sandbox-vrp",
"callback": "https://display-parameters.com/",
"controlParameters" : {
"maxAmountPerPayment" : {
"amount" : "10",
"currency" : "GBP"
},
"psuAuthenticationMethods" : ["SCA_NOT_REQUIRED"],
"periodicLimits" : [
{
"frequency" : "WEEKLY",
"alignment" : "CONSENT",
"totalMaxAmount" : {
"amount" : "50",
"currency" : "GBP"
}
},
{
"frequency" : "MONTHLY",
"alignment" : "CONSENT",
"totalMaxAmount" : {
"amount" : "200",
"currency" : "GBP"
}
}
]
},
"initiationDetails": {
"paymentIdempotencyId": "{uniqueValue}",
"reference": "Bills Coffee Shop",
"contextType": "OTHER",
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "{sortCode}"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
}
]
}
}
}'
Response:
{
"meta": {
"tracingId": "73b76af8d5104cd7a14d48fa3eea75c4"
},
"data": {
"id": "1aeeaf4a-2700-4ded-b47d-5d052abde50a",
"applicationUserId": "variable-recurring-payment-tutorial",
"institutionId": "natwest-sandbox-vrp",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-03-22T12:29:49.515Z",
"featureScope": [
"EXISTING_PAYMENTS_DETAILS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING"
],
"state": "dp230e7e-af86-4f7f-a486-5becc9744c36",
"institutionConsentId": "VRP-57faf1f2-99e0-43c2-a154-9200d6fead1c",
"authorisationUrl": "{authorisationUrl}",
"qrCodeUrl": "https://images.yapily.com/image/cd899180-676e-492d-80d3-40330a1b6b9e/consent-auth-url.png?size=0",
"controlParameters": {
"psuAuthenticationMethods": [
"SCA_NOT_REQUIRED"
],
"periodicLimits": [
{
"totalMaxAmount": {
"amount": 50.0,
"currency": "GBP"
},
"frequency": "WEEKLY",
"alignment": "CONSENT"
},
{
"totalMaxAmount": {
"amount": 200.0,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CONSENT"
}
],
"maxAmountPerPayment": {
"amount": 10.0,
"currency": "GBP"
}
},
"initiationDetails": {
"reference": "Bills Coffee Shop",
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "{sortCode}"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
}
]
}
}
}
}
-
The
SweepingAuthorisationResponse
returned includes the
authorisationUrl
that you should redirect the user to. - The user will be asked to login and authorise the payment with their bank. For this tutorial we use the Natwest sandbox credentials .
-
Upon completion the user will be redirected back to the
callback
url supplied in the request. In our example we are usinghttps://display-parameters.com/
, which will display the parameters returned with the redirect. The most important of which is theconsentToken
, which is used in the next steps to either confirm availability of funds or initiate the authorised payment.
3. Consent Confirmation
Optional - When the status
of the consent is AWAITING_AUTHORIZATION
, you can monitor the status until the consent
transitions to AUTHORIZED
confirming that the User
has authorised the payment request.
To do this, execute Get Sweeping Variable Recurring Payment Consent:
Request:
curl -L -X GET 'https://api.yapily.com/variable-recurring-payments/sweeping/consents/1aeeaf4a-2700-4ded-b47d-5d052abde50a' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
{
"meta": {
"tracingId": "003ca8c0ad7a4e0c9d4d98bba9fcff63"
},
"data": {
"id": "1aeeaf4a-2700-4ded-b47d-5d052abde50a",
"applicationUserId": "variable-recurring-payment-tutorial",
"status": "AUTHORIZED",
"createdAt": "2021-03-22T12:29:49.515Z",
"featureScope": [
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"EXISTING_PAYMENTS_DETAILS"
],
"consentToken": "{uniqueValue}",
"state": "dp230e7e-af86-4f7f-a486-5becc9744c36",
"authorizedAt": "2021-03-22T12:34:27.237329Z",
"institutionConsentId": "VRP-57faf1f2-99e0-43c2-a154-9200d6fead1c",
"controlParameters": {
"psuAuthenticationMethods": [
"SCA_NOT_REQUIRED"
],
"periodicLimits": [
{
"totalMaxAmount": {
"amount": 50.0,
"currency": "GBP"
},
"frequency": "WEEKLY",
"alignment": "CONSENT"
},
{
"totalMaxAmount": {
"amount": 200.0,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CONSENT"
}
],
"maxAmountPerPayment": {
"amount": 10.0,
"currency": "GBP"
}
},
"payer": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "{sortCode}"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
}
]
},
"initiationDetails": {
"reference": "REFERENCE",
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
}
}
}
-
The
SweepingAuthorisationResponse
returned is the same as the response from the Create Sweeping Authorisation request with the exception that the status may have been updated and theconsentToken
received along with the approvedpayer
details.
4. Confirm availability of funds
Optional - Once the user authorises the sweeping variable recurring payment request and you have the consentToken
, you have the option to check availability of funds in the payer
account before executing the payment.
To do this, execute Confirm Funds for Variable Recurring Payments by mentioning the reference
and paymentAmount
as the request body.
Request:
curl -L -X POST 'https://api.yapily.com/variable-recurring-payments/funds-confirmation' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"reference": "Bills Coffee Shop",
"paymentAmount": {
"amount": 10,
"currency": "GBP"
}
}'
Response:
{
"meta": {
"tracingId": "0cda48c70f3941148bbee775a65fa3d0"
},
"data": {
"id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
"reference": "Bills Coffee Shop",
"paymentAmount": {
"amount": 10.0,
"currency": "GBP"
},
"fundsAvailable": {
"fundsAvailable": true
}
}
}
-
The
FundsConfirmationResponse
returned includes
fundsAvailable
and having value astrue
indicates the availability of funds whereasfalse
indicates otherwise.
5. Create the payment
Once the user authorises the payment request and you have the consentToken
, you are able to execute the payment.
To do this, execute Create Variable Recurring Payment by mentioning the paymentIdempotencyId
,
psuAuthenticationMethod
and paymentAmount
as the request body.
Request:
curl -L -X POST 'https://api.yapily.com/variable-recurring-payments/payments' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"paymentIdempotencyId": "{uniqueValue}",
"psuAuthenticationMethod": "SCA_NOT_REQUIRED",
"paymentAmount": {
"amount": 10,
"currency": "GBP"
}
}'
Response:
{
"meta": {
"tracingId": "b04f21311f5a463f851ac093568cda56"
},
"data": {
"id": "19336ab2-efe1-4b0f-8008-09434c93137c",
"paymentIdempotencyId": "{uniqueValue}",
"institutionConsentId": "VRP-57faf1f2-99e0-43c2-a154-9200d6fead1c",
"status": "PENDING",
"statusDetails": {
"status": "PENDING",
"statusUpdateDate": "2021-03-25T07:48:16.102Z",
"isoStatus": {
"code": "PDNG",
"name": "Pending"
}
},
"initiationDetails": {
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
},
"submissionDetails": {
"reference": "Bills Coffee Shop",
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"paymentAmount": {
"amount": 10.0,
"currency": "GBP"
}
}
}
}
-
The
SubmissionResponse
returned includes the
status
and theid
. Thestatus
ofPENDING
indicates the request is being processed but is not yetCOMPLETED
. -
COMPLETED
indicates that theInstitution
has accepted the payment initiation request and will later proceed with settlement -
If you receive a
status
ofPENDING
, you can use thepayment-id
to poll the paymentstatus
until it transitions toCOMPLETED
orFAILED
.
6. Payment Confirmation
Optional - When the status
of the payment is PENDING
, you will need to monitor the status until the payment
transitions to COMPLETED
confirming that the Institution
has accepted the payment initiation request.
To do this, execute Get Variable Recurring Payment Details:
Request:
curl -L -X GET 'https://api.yapily.com/variable-recurring-payments/payments/19336ab2-efe1-4b0f-8008-09434c93137c/details' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
{
"meta": {
"tracingId": "8cd7ab7e8db84cc6a91e6f30277ebdba"
},
"data": {
"id": "19336ab2-efe1-4b0f-8008-09434c93137c",
"paymentIdempotencyId": "{uniqueValue}",
"institutionConsentId": "VRP-57faf1f2-99e0-43c2-a154-9200d6fead1c",
"status": "COMPLETED",
"statusDetails": {
"status": "COMPLETED",
"statusUpdateDate": "2021-03-25T07:49:16.102Z",
"isoStatus": {
"code": "ACSC",
"name": "AcceptedSettlementCompleted"
}
},
"initiationDetails": {
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
},
"submissionDetails": {
"reference": "Bills Coffee Shop",
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"paymentAmount": {
"amount": 10.0,
"currency": "GBP"
}
}
}
}
-
The
SubmissionResponse
returned is exactly the same as the response from the Create Variable Recurring Payment request with the exception that the status may have been updated.
Congratulations! You've just created an Open Banking sweeping variable recurring payment via Yapily.