Tutorial: Make a sweeping variable recurring payment

Yapily Variable Recurring Payments is available as a Beta version.

This tutorial walks through how to create a UK domestic sweeping variable recurring payment with the Natwest Sandbox.

1. Select bank

To find which banks support sweeping variable recurring payments use GET institutions to retrieve the list of your supported institutions.

Request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/institutions' \
  -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy

Copied

{  
  "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_SWEEPING. 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 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.

Note: Yapily Connect customers must provide payer details in the complianceData object to meet compliance requirements.

Request:

Copy

Copied

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}"
                }
            ]
        }
      },
      "complianceData": {
        "payer": {
            "type": "INDIVIDUAL",
            "individual": {
                "name": "John Doe",
                "birthDate": "2000-08-12"
            }
        }
      }
   }'

Response:

Copy

Copied

{
    "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 using https://display-parameters.com/ , which will display the parameters returned with the redirect. The most important of which is the consentToken , 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:

Copy

Copied

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:

Copy

Copied

{
    "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 the consentToken received along with the approved payer 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:

Copy

Copied

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:

Copy

Copied

{
  "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 as true indicates the availability of funds whereas false 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:

Copy

Copied

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:

Copy

Copied

{
    "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 the id . The status of PENDING indicates the request is being processed but is not yet COMPLETED .
COMPLETED indicates that the Institution has accepted the payment initiation request and will later proceed with settlement
If you receive a status of PENDING , you can use the payment-id to poll the payment status until it transitions to COMPLETED or FAILED .

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:

Copy

Copied

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:

Copy

Copied

{
    "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.

Tutorial: Make a sweeping variable recurring payment

1. Select bank

2. Authorisation

3. Consent Confirmation

4. Confirm availability of funds

5. Create the payment

6. Payment Confirmation

Related Tutorials