Guides

Making a Payment

Introduction

This guide outlines how to send money using the Modulr API.

The API supports three ways of sending funds:

• To another Modulr account: type ACCOUNT
• To an external bank account using the Sort Code and Account number: type SCAN
• To an external bank account already added as a Beneficiary: type BENEFICIARY

All payment requests require you to specify the source Modulr account for the payment. The destination type will vary depending on the destination type.

SCAN and BENEFICIARY requests are validated against the standard UK Modulus checks for Sort Code and Account Number. Details of these checks can be found here.

A sample of Sort Code / Account Numbers that will fail this check are;

• 938063 / 15763217
• 118765 / 64371388
• 203099 / 66831036

A sample of Sort Code / Account Numbers that will pass this check are;

• 134020 / 63849203
• 118765 / 64371389
• 200915 / 41011166

Payment to SCAN

Create a payment request to an external bank account specifying the Sort Code and Account Number.

Request

POST https://api-sandbox.modulrfinance.com/api-sandbox/payments
{
  "amount": 1,
  "destination": {
    "accountNumber": "22446688",
    "sortCode": "112233",
    "name": "A N Payee",
    "type": "SCAN"
  },
  "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
  "reference": "Payment 123",
  "sourceAccountId": "A12002MW"
}

Response

HTTP/1.1 201 Created
{
    "details": {
        "sourceAccountId": "A12002MW",
        "destinationType": "SCAN",
        "destination": {
            "type": "SCAN",
            "accountNumber": "22446688",
            "sortCode": "112233",
            "name": "A N Payee"
        },
        "amount": 1,
        "reference": "Payment 123",
        "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7"
    },
    "createdDate": "2017-02-02T16:59:36.877+0000",
    "id": "P120003AQJ",
    "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
    "status": "VALIDATED"
}

Payment to a Beneficiary

Make a Faster Payment to an existing Beneficiary using the Beneficiary ID.

Request

POST https://api-sandbox.modulrfinance.com/api-sandbox/payments
{
    "amount": 1.50,
    "destination": {
        "id": "B12001EZ",
        "type": "BENEFICIARY"
    },
    "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
    "reference": "Payment 456",
    "sourceAccountId": "A12002MW"
}

Response

HTTP/1.1 201 Created
{
    "details": {
        "sourceAccountId": "A12002MW",
        "destinationId": "B12001EZ",
        "destinationType": "BENEFICIARY",
        "destination": {
            "type": "BENEFICIARY",
            "id": "B12001EZ"
        },
        "amount": 1.5,
        "reference": "Payment 456"

    },
    "createdDate": "2017-02-02T17:00:57.172+0000",
    "id": "P120003AQK",
    "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
    "status": "VALIDATED"
}

Payment to a Modulr Account

Transfer funds to another Account on the Modulr platform.

Request

POST https://api-sandbox.modulrfinance.com/api-sandbox/payments
{
  "amount": 250,
  "destination": {
    "id": "A1200BUT",
    "type": "ACCOUNT"
  },
  "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
  "reference": "Payment 789",
  "sourceAccountId": "A12002MW"
}

Response

HTTP/1.1 201 Created
{
    "details": {
        "sourceAccountId": "A12002MW",
        "destinationId": "A1200BUT",
        "destinationType": "ACCOUNT",
        "destination": {
            "type": "ACCOUNT",
            "id": "A1200BUT"
        },
        "amount": 250,
        "reference": "Payment 789",

    },
    "createdDate": "2017-02-02T17:01:47.147+0000",
    "id": "P120003AQM",
    "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
    "status": "VALIDATED"
}

Query Payment status

The /payments/ endpoint is asynchronous - the payment status returned on the initial request will update as the payment is processed. You should check the payment status after a short interval to allow for processing to get the final status for a payment.

You can check the status of the newly created Payment by querying it by it by it’s id.

Request

GET https://api-sandbox.modulrfinance.com/api-sandbox/payments?id=P120002369

Response

HTTP/1.1 200 OK
{
    "content": [{
        "id": "P120002369",
        "status": "PROCESSED",
        "details": {
            "reference": "Payment 123",
            "externalReference": "c3035952-b6f3-11e6-80f5-76304dec7eb7",
            "amount": 1,
            "sourceAccountId": "A12002MW",
            "destination": {
                "name": "A N Payee",
                "type": "SCAN",
                "sortCode": "112233",
                "accountNumber": "22446688"
            }
        },
        "createdDate": "2016-11-30T11:57:26.739+0000"
    }],
    "size": 1,
    "totalSize": 1,
    "page": 0,
    "totalPages": 1
}

Payment Statuses

A Payment object can have the following statuses:

Payment Status	Description	State
Sucess / Pending statuses
SUBMITTED	Request has been accepted - will go to internal validation	Transient
VALIDATED	Request internally validated - request has been validated  and now is queued to be sent to external system	Transient
PROCESSED	Request processed successfully  sent to external system.	Final
Error statuses
ER_INVALID	Failed internal validations - incorrect data like no funds,  account inactive, no destination beneficiary etc	Final
ER_EXTCONN	Issues with external system connectivity - will be retried	Transient
ER_EXTSYS	Rejected by external system	Final
ER_GENERAL	General error, covering any other errors	Final
ER_BATCH	Rejected due to strict processing of BatchRequest - Not  relevant to single payments	Final