Create a Bulk Domestic Payment

This tutorial walks you through each of the steps required to complete an Open Banking Bulk Payment using Yapily.

This tutorial walks through how to create a UK Domestic Bulk Payment with the Modelo Sandbox. Each step contains links to further reading for more detailed information.

1 Get Institutions

2 Authorisation

3 Create the payment

4 Get Status

1. Get Institutions

Optional - This step is optional as it is entirely possible to make a payment without retrieving the Institution list, however it is often required to display a list of supported banks to allow the user to choose which bank they would like to make a payment from.

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

To display this list, use GET Institutions:

Request:


curl --location --request GET 'https://api.yapily.com/institutions' \
  --header 'Authorization: Basic {authToken}'

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 Bulk Payment, we can offer any institution that supports the feature CREATE_BULK_PAYMENT.
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 Institution id 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 bulk 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 Bulk Payment Authorisation:

Request:


curl --location --request POST 'https://api.yapily.com/bulk-payment-auth-requests' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {authToken}' \
  --data-raw '{
      "applicationUserId": "bulk-payment-tutorial",
      "institutionId": "modelo-sandbox",
      "callback": "https://display-parameters.com/",
      "paymentRequest": {
          "payments": [
              {
                  "type": "DOMESTIC_PAYMENT",
                  "reference": "Payment 1",
                  "paymentIdempotencyId": "{uniqueValue}",
                  "amount": {
                      "amount": 8.70,
                      "currency": "GBP"
                  },
                  "payee": {
                      "name": "BILLS COFFEE LTD",
                      "accountIdentifications": [
                          {
                              "type": "ACCOUNT_NUMBER",
                              "identification": "{accountNumber}"
                          },
                          {
                              "type": "SORT_CODE",
                              "identification": "{sortCode}"
                          }
                      ],
                      "address": {
                          "country": "GB"
                      }
                  }
              },
              {
                  "type": "DOMESTIC_PAYMENT",
                  "reference": "Payment 2",
                  "paymentIdempotencyId": "{uniqueValue}",
                  "amount": {
                      "amount": 8.70,
                      "currency": "GBP"
                  },
                  "payee": {
                      "name": "BILLS COFFEE LTD",
                      "accountIdentifications": [
                          {
                              "type": "ACCOUNT_NUMBER",
                              "identification": "{accountNumber}"
                          },
                          {
                              "type": "SORT_CODE",
                              "identification": "{sortCode}"
                          }
                      ],
                      "address": {
                          "country": "GB"
                      }
                  }
              }
          ]
      }
  }'

Response:


{
  "meta": {
    "tracingId": "611f74cb4f3205d983ebb2fca59d0847"
  },
  "data": {
    "id": "af563bac-e50a-42bd-91bc-581813e13733",
    "userUuid": "f3be3c23-bd0e-475e-b389-62dd1f5aa6c1",
    "applicationUserId": "bulk-payment-tutorial",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-03-03T09:23:45.841Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "CREATE_BULK_PAYMENT"
    ],
    "state": "6b07bddf9e7746ae8ecb7cbecc00f19a",
    "institutionConsentId": "sdp-1-469c63ef-e6b6-4dd2-88b7-3aea0bff4136",
    "authorisationUrl": "{authorisationUrl}",
    "qrCodeUrl": "https://images.yapily.com/image/55b6b6bc-daa8-490c-89e1-243156868e00/1614763426?size=0"
  }
}

The PaymentAuthorisationRequestResponse 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 sandbox credentials: mits / mits.
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 step to initiate the authorised payment.

3. 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 Bulk Payment using the same paymentRequest object specified in step 2 as the request body.

Request:


curl --location --request POST 'https://api.yapily.com/bulk-payments' \
  --header 'Content-Type: application/json' \
  --header 'Consent: {consentToken}' \
  --header 'Authorization: Basic {authToken}' \
  --data-raw '{
      "payments": [
          {
              "type": "DOMESTIC_PAYMENT",
              "reference": "Payment 1",
              "paymentIdempotencyId": "{uniqueValue}",
              "amount": {
                  "amount": 8.70,
                  "currency": "GBP"
              },
              "payee": {
                  "name": "BILLS COFFEE LTD",
                  "accountIdentifications": [
                      {
                          "type": "ACCOUNT_NUMBER",
                          "identification": "{accountNumber}"
                      },
                      {
                          "type": "SORT_CODE",
                          "identification": "{sortCode}"
                      }
                  ],
                  "address": {
                      "country": "GB"
                  }
              }
          },
          {
              "type": "DOMESTIC_PAYMENT",
              "reference": "Payment 2",
              "paymentIdempotencyId": "{uniqueValue}",
              "amount": {
                  "amount": 8.70,
                  "currency": "GBP"
              },
              "payee": {
                  "name": "BILLS COFFEE LTD",
                  "accountIdentifications": [
                      {
                          "type": "ACCOUNT_NUMBER",
                          "identification": "{accountNumber}"
                      },
                      {
                          "type": "SORT_CODE",
                          "identification": "{sortCode}"
                      }
                  ],
                  "address": {
                      "country": "GB"
                  }
              }
          }
      ]
  }'

Response:


{
  "meta": {
    "tracingId": "0cda48c70f3941148bbee775a65fa3d0"
  },
  "data": {
    "id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
    "institutionConsentId": "sdp-6-b06f9a82-c641-4aba-b76d-43e6bc052f75",
    "status": "PENDING",
    "statusDetails": {
      "status": "PENDING",
      "statusUpdateDate": "2021-06-09T13:53:28.67Z"
    },
    "createdAt": "2021-06-09T13:53:28.67Z",
    "bulkAmountSum": 7
  }
}

The PaymentResponse 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 the PENDING status, you can use the payment-id to poll the payment status until it transitions to COMPLETED or FAILED.

4. 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 Payment Details:

Request:


curl --location --request GET 'https://api.yapily.com/payments/pv3-6c0f031d-6786-4845-9799-bdd2e89ba362/details' \
  --header 'Content-Type: application/json' \
  --header 'Consent: {consentToken}' \
  --header 'Authorization: Basic {authToken}'

Response:


{
  "meta": {
    "tracingId": "0cda48c70f3941148bbee775a65fa3d0"
  },
  "data": {
    "id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
    "institutionConsentId": "sdp-6-b06f9a82-c641-4aba-b76d-43e6bc052f75",
    "status": "COMPLETED",
    "statusDetails": {
      "status": "COMPLETED",
      "statusUpdateDate": "2021-06-09T13:53:28.67Z"
    },
    "createdAt": "2021-06-09T13:53:28.67Z",
    "bulkAmountSum": 7
  }
}

The PaymentResponse returned is exactly the same as the response from the Create Bulk Payment request with the exception that the status may have been updated.

Congratulations, if you got this far, you've just created an Open Banking payment via Yapily.

Get Financial Data

Create a Bulk Domestic Payment

1. Get Institutions

2. Authorisation

3. Create the payment

4. Payment Confirmation

Related Tutorials