Single payments
Introduction
A single payment is 1 payment for a specified amount which the end user can configure from an institution to pay an entity.
You can create both domestic and international single payments with the Yapily API.
Looking for our quickest integration option?
See Yapily Hosted Pages which provides a pre-built and hosted UI to quickly and easily facilitate single payments.
Domestic single payments
Domestic single payments are possible when the institution supports the feature CREATE_DOMESTIC_SINGLE_PAYMENT
.
To create a single domestic payment, you need to provide the following properties as part of the paymentRequest object:
Property | Description |
---|---|
type required |
The payment type to use. |
paymentIdempotencyId required |
The unique identifier for the payment. Any alpha-numeric string less than or equal to 35 characters. |
amount required |
The monetary value and currency. |
payee required |
Details of the beneficiary. |
reference optional |
The payment reference or description. Any string less than 18 characters. |
payer conditional |
Details of the benefactor. See payer details for more information. |
"paymentRequest": {
"type": "DOMESTIC_PAYMENT",
"paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
"amount": {
"amount": "1.00",
"currency": "GBP"
},
"payee": {
"name": "Jane Doe",
"address": {
"country": "GB"
},
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "123456"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"reference": "Bill Payment",
}
Payer details
Specifying the payer details in the paymentRequest
object is conditional on the country you are making the payment in.
The Payer
object is not required in:
- Belgium
-
France
-
Few exceptions:
- The payer(debtor) name is required to make the payment for Crédit Mutuel(Arkea) banking group.
-
Few exceptions:
- Ireland
- Netherlands
- Portugal
- Spain
- UK
Some banks may require additional information. Please contact our support for details.
For all other countries in Europe, you must provide the Payer
object with details of the benefactor.
You can obtain the payer details by accessing the user's account information using AIS, requesting the details from the user or providing information you have already gathered from the user.
For countries in Europe, the accountIdentifications
object should just contain the IBAN
.
In the UK, the accountIdentifications
object should contain the ACCOUNT_NUMBER
and SORT_CODE
.
"paymentRequest": {
...
"payer": {
"name": "John Doe",
"accountIdentifications": [
{
"type": "IBAN",
"identification": "DE12345678901234567890"
}
]
}
}
"paymentRequest": {
...
"payer": {
"name": "John Doe",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{
"type": "SORT_CODE",
"identification": "123456"
}
]
}
}
Note: If you specify the payer details, this will force the user to make the payment from the specified account.
SEPA payments
It is also possible to execute SEPA payments as domestic payments.
To find out more, see European Payments.
International single payments
International payments are currently available as a BETA version.
International single payments are possible when the institution supports the feature CREATE_INTERNATIONAL_SINGLE_PAYMENT
.
To create an international single payment, you need to provide the properties required for a domestic single payment as well as the following additional properties in the PaymentRequest.
Note: The same additional properties are required for a scheduled or periodic international payment.
Property | Description |
---|---|
payee.address conditional |
The address of the payee. Required when the payment type is international. |
internationalPayment conditional |
Specifies the properties to define an international payment. Must be specified when payment type :INTERNATIONAL_PAYMENT ,INTERNATIONAL_SCHEDULED_PAYMENT , INTERNATIONAL_PERIODIC_PAYMENT |
internationalPayment.currencyOfTransfer required |
The 3 letter currency code for the currency of the payment to be transferred to. This can differ from the currency of the payer's account. |
internationalPayment.chargeBearer optional |
Specifies who should bear the charges associated with processing the payment transaction. |
internationalPayment.priority optional |
Specifies the priority of the payment. |
internationalPayment.purpose optional |
Indicate the external purpose as a ISO20022 purpose code value. |
note
For all countries the payee.accountIdentifications
object must contain an IBAN
for international payments.
"paymentRequest": {
"type": "INTERNATIONAL_PAYMENT",
"paymentIdempotencyId": "4289457hd38djoa783jw9qag2",
"amount": {
"amount": "1.00",
"currency": "GBP"
},
"payee": {
"name": "Jane Doe",
"address": {
"streetName": "Sample Street",
"buildingNumber": "1",
"postCode": "AB1 2CD",
"country": "GB"
},
"accountIdentifications": [
{
"type": "BIC",
"identification": "RBOSGB2109M"
},
{
"type": "IBAN",
"identification": "GB29RBOS83040210126939"
}
]
},
"reference": "Bill Payment",
"internationalPayment": {
"currencyOfTransfer": "USD",
"chargeBearer": "DEBT",
"priority": "NORMAL",
"purpose": "GDDS"
}
}
See more information in the API reference.
Charges
International payments are executed with cross-border charges. These are passed on to the user and should be displayed by the institution once the user is redirected to give their authorisation.