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.
Copy
Copied
"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.
  • Ireland
  • Netherlands
    • Exception:
      • The payer(debtor) account identifications with country is required to make the payment for Handelsbanken - 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.

EuropeUK
Copy
Copied
"paymentRequest": {
  ...
  "payer": {
    "name": "John Doe",
    "accountIdentifications": [
      {
        "type": "IBAN",
        "identification": "DE12345678901234567890"
      }
    ]
  }
}
Copy
Copied
"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.

Copy
Copied
"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.