Tutorial: Make a non-sweeping variable recurring payment
Yapily Variable Recurring Payments is available as a Beta version.
This tutorial walks through how to create a UK domestic non-sweeping variable recurring payment with the Natwest Sandbox.
1. Select bank
To find which banks support non-sweeping variable recurring payments use GET institutions to retrieve the list of your supported 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"
]
}
]
}
Filter the list for all institutions that support the feature CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING
. Then display these institutions in your application so the user can select which bank to make the payment from.
Once the user selects a bank, store the id
of the institution to use in step 2.
2. Authorisation
After obtaining the institution-id
and confirming that the bank supports the ability to make a domestic non-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 Non-Sweeping Authorisation.
Note: Yapily Connect customers must provide payer details in the complianceData
object to meet compliance requirements.
Request:
curl -L -X POST 'https://api.yapily.com/variable-recurring-payments/non-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" : {
"maxCumulativeNumberOfPayments" : "12",
"maxCumulativeAmount" : {
"amount" : "1200",
"currency" : "GBP"
},
"maxAmountPerPayment" : {
"amount" : "100",
"currency" : "GBP"
},
"psuAuthenticationMethods" : ["SCA_NOT_REQUIRED"],
"periodicLimits" : [
{
"frequency" : "MONTHLY",
"alignment" : "CALENDAR",
"totalMaxAmount" : {
"amount" : "100",
"currency" : "GBP"
},
"maxNumberOfPayments" : "2"
},
{
"frequency" : "YEARLY",
"alignment" : "CALENDAR",
"totalMaxAmount" : {
"amount" : "1200",
"currency" : "GBP"
},
"maxNumberOfPayments" : "12"
}
]
},
"initiationDetails": {
"paymentIdempotencyId": "{uniqueValue}",
"reference": "Subscription",
"contextType": "BILL",
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "{sortCode}"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
}
]
}
},
"complianceData": {
"payer": {
"type": "INDIVIDUAL",
"individual": {
"name": "John Doe",
"birthDate": "2000-08-12"
}
}
}
}'
Response:
{
"meta": {
"tracingId": "611f74cb4f3205d983ebb2fca59d0847"
},
"data": {
"id": "9a14e525-044d-4bfe-8c02-e0167fe4fd77",
"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_NONSWEEPING"
],
"state": "dp2d4d33-1b9f-4f60-b6bc-2159f83f3c88",
"institutionConsentId": "VRP-89b98300-7580-4af3-b163-786243c4a124",
"authorisationUrl": "{authorisationUrl}",
"qrCodeUrl": "https://images.yapily.com/image/55b6b6bc-daa8-490c-89e1-243156868e00/1614763426?size=0",
"controlParameters" : {
"maxCumulativeNumberOfPayments" : "12",
"maxCumulativeAmount" : {
"amount" : "1200",
"currency" : "GBP"
},
"maxAmountPerPayment" : {
"amount" : "100",
"currency" : "GBP"
},
"psuAuthenticationMethods" : ["SCA_NOT_REQUIRED"],
"periodicLimits" : [
{
"frequency" : "MONTHLY",
"alignment" : "CALENDAR",
"totalMaxAmount" : {
"amount" : "100",
"currency" : "GBP"
},
"maxNumberOfPayments" : "2"
},
{
"frequency" : "YEARLY",
"alignment" : "CALENDAR",
"totalMaxAmount" : {
"amount" : "1200",
"currency" : "GBP"
},
"maxNumberOfPayments" : "12"
}
]
},
"initiationDetails": {
"paymentIdempotencyId": "{uniqueValue}",
"reference": "Subscription",
"contextType": "BILL",
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "{sortCode}"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
}
]
}
}
}
}
-
The
NonSweepingAuthorisationResponse
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 Non-Sweeping Variable Recurring Payment Consent:
Request:
curl -L -X GET 'https://api.yapily.com/variable-recurring-payments/non-sweeping/consents/9a14e525-044d-4bfe-8c02-e0167fe4fd77' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
{
"meta": {
"tracingId": "003ca8c0ad7a4e0c9d4d98bba9fcff63"
},
"data": {
"id": "9a14e525-044d-4bfe-8c02-e0167fe4fd77",
"applicationUserId": "variable-recurring-payment-tutorial",
"status": "AUTHORIZED",
"createdAt": "2021-03-22T12:29:49.515Z",
"featureScope": [
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"EXISTING_PAYMENTS_DETAILS"
],
"consentToken": "{uniqueValue}",
"state": "dp2d4d33-1b9f-4f60-b6bc-2159f83f3c88",
"authorizedAt": "2021-03-22T12:34:27.237329Z",
"institutionConsentId": "VRP-89b98300-7580-4af3-b163-786243c4a124",
"controlParameters": {
"psuAuthenticationMethods": [
"SCA_NOT_REQUIRED"
],
"periodicLimits": [
{
"totalMaxAmount": {
"amount": 100.0,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CALENDAR",
"maxNumberOfPayments": 2
},
{
"totalMaxAmount": {
"amount": 1200.0,
"currency": "GBP"
},
"frequency": "YEARLY",
"alignment": "CALENDAR",
"maxNumberOfPayments": 12
}
],
"maxAmountPerPayment": {
"amount": 100.0,
"currency": "GBP"
},
"maxCumulativeAmount": {
"amount": 1200,
"currency": "GBP"
},
"maxCumulativeNumberOfPayments": 12
},
"payer": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "{sortCode}"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
}
]
},
"initiationDetails": {
"reference": "Subscription",
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
}
}
}
-
The
NonSweepingAuthorisationResponse
returned is the same as the response from the Create Non-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 non-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": "Subscription",
"paymentAmount": {
"amount": 100,
"currency": "GBP"
}
}'
Response:
{
"meta": {
"tracingId": "0cda48c70f3941148bbee775a65fa3d0"
},
"data": {
"id": "6ae8b8be-d927-4346-a3e3-83dab57e2c9a",
"reference": "Subscription",
"paymentAmount": {
"amount": 100.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 including 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": 100,
"currency": "GBP"
}
}'
Response:
{
"meta": {
"tracingId": "e1ce71c91d81460aa448a1e6656c5574"
},
"data": {
"id": "b3af3f56-2ae0-4222-bc6d-9f2ac1c427e8",
"paymentIdempotencyId": "{uniqueValue}",
"institutionConsentId": "VRP-89b98300-7580-4af3-b163-786243c4a124",
"status": "PENDING",
"statusDetails": {
"status": "PENDING",
"statusUpdateDate": "2021-03-25T07:48:16.102Z",
"isoStatus": {
"code": "PDNG",
"name": "Pending"
}
},
"initiationDetails": {
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
},
"submissionDetails": {
"reference": "Subscription",
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"paymentAmount": {
"amount": 100.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
asPENDING
, 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/b3af3f56-2ae0-4222-bc6d-9f2ac1c427e8/details' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
{
"meta": {
"tracingId": "e5c1c42aa94541598877999e892f7a8a"
},
"data": {
"id": "b3af3f56-2ae0-4222-bc6d-9f2ac1c427e8",
"paymentIdempotencyId": "{uniqueValue}",
"institutionConsentId": "VRP-89b98300-7580-4af3-b163-786243c4a124",
"status": "COMPLETED",
"statusDetails": {
"status": "COMPLETED",
"statusUpdateDate": "2021-03-25T07:49:16.102Z",
"isoStatus": {
"code": "ACSC",
"name": "AcceptedSettlementCompleted"
}
},
"initiationDetails": {
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
},
"submissionDetails": {
"reference": "Subscription",
"payee": {
"name": "NETFLIX",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"paymentAmount": {
"amount": 100.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 non-sweeping variable recurring payment via Yapily.