Tutorial: Make a single payment
Introduction
This tutorial explains how to create a UK domestic single payment with the Modelo Sandbox.
Note: All requests made to the Yapily API require basic authentication.
Overview of steps
The following diagram illustrates how to create a UK domestic single payment:
1. Select bank
To find which banks support single domestic 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_SINGLE_PAYMENT. 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 payment authorisation including the institution ID, your callback URL and the paymentRequest object.
Request:
curl -L -X POST 'https://api.yapily.com/payment-auth-requests' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"applicationUserId": "single-payment-tutorial",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/",
"paymentRequest": {
"type": "DOMESTIC_PAYMENT",
"reference": "Bills Coffee Shop",
"paymentIdempotencyId": "{uniqueValue}",
"amount": {
"amount": 8.70,
"currency": "GBP"
},
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
}
}'Response:
{
"meta": {
"tracingId": "611f74cb4f3205d983ebb2fca59d0847"
},
"data": {
"id": "af563bac-e50a-42bd-91bc-581813e13733",
"userUuid": "f3be3c23-bd0e-475e-b389-62dd1f5aa6c1",
"applicationUserId": "single-payment-tutorial",
"institutionId": "modelo-sandbox",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-03-03T09:23:45.841Z",
"featureScope": [
"EXISTING_PAYMENTS_DETAILS",
"CREATE_DOMESTIC_SINGLE_PAYMENT",
"EXISTING_PAYMENT_INITIATION_DETAILS"
],
"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"
}
}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 Modelo sandbox credentials are: mits / mits.
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 creating the payment in step 3.
3. Create payment
Create the payment specifying the consentToken in the header and the contents of the paymentRequest object in step 2 as the body.
Request:
curl -L -X POST 'https://api.yapily.com/payments' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"type": "DOMESTIC_PAYMENT",
"reference": "Bills Coffee Shop",
"paymentIdempotencyId": "{uniqueValue}",
"amount": {
"amount": 8.70,
"currency": "GBP"
},
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
}
}'Response:
{
"meta": {
"tracingId": "0f07ebe9be5fbec0dd660c4e091bd181"
},
"data": {
"id": "pv3-6c0f031d-6786-4845-9799-bdd2e89ba362",
"institutionConsentId": "sdp-1-469c63ef-e6b6-4dd2-88b7-3aea0bff4136",
"paymentIdempotencyId": "{uniqueValue}",
"paymentLifecycleId": "69d55454ea74546e8b1b44efb17fc45",
"status": "PENDING",
"statusDetails": {
"status": "PENDING",
"isoStatus": {
"code": "PDNG",
"name": "Pending"
}
"statusUpdateDate": "2021-03-03T09:41:48.253Z"
},
"payeeDetails": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"reference": "Bills Coffee Shop",
"amount": 8.70,
"currency": "GBP",
"amountDetails": {
"amount": 8.70,
"currency": "GBP"
},
"createdAt": "2021-03-03T09:41:48.253Z"
}
}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.
4. 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:
- subscribing to receive payment notifications
OR
-
polling the payment details using the payment
idfrom step 3
Retrieve the payment details manually by executing get payment details.
Request:
curl -L -X GET 'https://api.yapily.com/payments/{paymentId}/details' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'Response:
{
"meta": {
"tracingId": "70c912118c3364f98f1c9dec073c3443"
},
"data": {
"payments": [
{
"id": "pv3-6c0f031d-6786-4845-9799-bdd2e89ba362",
"institutionConsentId": "sdp-1-469c63ef-e6b6-4dd2-88b7-3aea0bff4136",
"paymentIdempotencyId": "{uniqueValue}",
"paymentLifecycleId": "69d55454ea74546e8b1b44efb17fc45",
"status": "COMPLETED",
"statusDetails": {
"status": "COMPLETED",
"isoStatus": {
"code": "ACTC",
"name": "AcceptedTechnicalValidation"
}
"statusUpdateDate": "2021-03-03T09:41:48.253Z"
},
"payeeDetails": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"reference": "Bills Coffee Shop",
"amount": 8.70,
"currency": "GBP",
"amountDetails": {
"amount": 8.70,
"currency": "GBP"
},
"createdAt": "2021-03-03T09:41:48.253Z"
}
]
}
}