Tutorial: Make a sweeping variable recurring payment

Yapily Variable Recurring Payments is available as a Private Beta version.

Introduction

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

Note: All requests made to the Yapily API require basic authentication.

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. Authorise

note

This example uses a single redirect flow using a callback URL.

Execute create sweeping authorisation including the institution ID, control parameters, initiation details and your callback URL.

Note: Yapily Connect customers must also 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}"
                    }
                ]
            }
        }
    }
}

Redirect the user to the authorisationUrl returned in the response.

The user is then asked to login and authorise the payment with their bank. The Natwest sandbox credentials are CustomerNumber: 123456789012. When prompted to enter your PIN and Password, Natwest Sandbox will display the values to enter above each text box.

Upon completion, the user is redirected back to the callback URL supplied in the request. In this example, the callback is https://display-parameters.com/ which displays the parameters returned with the redirect.

Store the consentToken to use when confirming availability of funds in step 3 and creating the payment in step 4.

3. Confirm availability of funds

note

This is an optional step, however confirming the availability of funds in the payer account before executing the payment reduces the possibility of a failed payment due to lack of funds.

Confirm availability of funds specifying the reference and paymentAmount in 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
    }
  }
}

fundsAvailable indicates whether the payer has sufficient funds available for the payment.

If the value is true proceed to step 4 to execute the payment.

If the value is false the payer has insufficient funds for the payment so the payment will fail if executed.

4. Create payment

Create the sweeping variable recurring payment specifying the paymentIdempotencyId, psuAuthenticationMethod and paymentAmount in 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 payment status, which describes the state of the payment, is returned in the response.

If the status is PENDING, you can use the payment id to poll the payment status until it transitions to COMPLETED or FAILED as in step 4.

For more information see payment status.

5. Confirm payment

note

This is an optional step, however we recommend monitoring the status of the payment when its PENDING to confirm if the institution accepts the payment initiation request.

You can confirm the status of the payment by polling the payment details using the payment id from step 4.

Execute get variable recurring payment details, specifying the paymentId in the path.

Request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/variable-recurring-payments/payments/{paymentId}/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"
            }
        }
    }
}