Sign in

v1

latestOpenAPI 3.1.0© Modulr Finance2026-08-04207430590.4 KB
Payments

Create a payment

Supports both Payments to external bank accounts via Faster Payments and transfers to other Modulr accounts. Requests to Payments are asynchronous.

post/payments

Request body

sourceAccountIdstring required

Identifier for the sending Account.

currency'GBP' | 'EUR' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'SHP' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'

Currency of the account in ISO 4217 format. Default is GBP

amountnumber

Amount of the payment in Major Current Units - '1' = 1.00 GBP

referencestring

Reference to be used for the Payment. This will appear on the Account statement/the recipient's bank account. Min 6 to max 18 characters that are not all the same (up to 140 characters for currencies other than GBP). Can contain alphanumeric, '-', '.', '&', '/' and space.

externalReferencestring

Your reference for this payment

endToEndReferencestring

Optional end to end reference. For international payments, Modulr payment ID will be used as end-to-end reference.

paymentDatestring

The future date on which to make the payment. Date format 'yyyy-MM-dd'.

Not applicable for international payments which will be submitted on date of submission or next working day, in line with cut-offs.

purposeOfPayment'BKFE' | 'BKIP' | 'BKPP' | 'CBLK' | 'ACCT' | 'CASH' | 'COLL' | 'CSDB' | 'DEPT' | 'INTC' | 'INTP' | 'LIMA' | 'NETT' | 'EXTD' | 'OTCD' | 'REPO' | 'SBSC' | 'SLEB' | 'AGRT' | 'AREN' | 'BEXP' | 'BOCE' | 'COMC' | 'CPYR' | 'GDSV' | 'GSCB' | 'LICF' | 'ROYA' | 'SERV' | 'SUBS' | 'SUPP' | 'TRAD' | 'CHAR' | 'COMT' | 'ECPR' | 'EPAY' | 'CLPR' | 'COMP' | 'DBTC' | 'HLRP' | 'HLST' | 'INPC' | 'INPR' | 'INSC' | 'INSU' | 'INTE' | 'LBRI' | 'LIFI' | 'LOAN' | 'LOAR' | 'PENO' | 'PPTI' | 'RELG' | 'TRFD' | 'FORW' | 'FXNT' | 'BLDM' | 'BNET' | 'CDBL' | 'CORT' | 'CPKC' | 'EDUC' | 'FAND' | 'FEES' | 'GIFT' | 'GOVT' | 'INSM' | 'IVPT' | 'REBT' | 'REFU' | 'RENT' | 'REOD' | 'TCSC' | 'CMDT' | 'DERI' | 'DIVD' | 'FREX' | 'HEDG' | 'INVS' | 'SAVG' | 'SECU' | 'TREA' | 'FNET' | 'FUTR' | 'DNTS' | 'HLTI' | 'LTCF' | 'MDCS' | 'VIEW' | 'SWFP' | 'SWPP' | 'SWRS' | 'SWUF' | 'ADCS' | 'ALMY' | 'BECH' | 'BENE' | 'BONU' | 'COMM' | 'HREC' | 'PEFC' | 'PENS' | 'SALA' | 'SSBE' | 'LREB' | 'LREV' | 'ESTX' | 'HSTX' | 'INTX' | 'PTXP' | 'RDTX' | 'TAXS' | 'VATX' | 'WHLD' | 'TAXR' | 'CBTV' | 'ELEC' | 'GASB' | 'PHON' | 'UBIL' | 'WTER' | 'GAMB' | 'LOTT' | 'PCOM' | 'PDEP' | 'PLDS' | 'PLRF'

A code from the UK Recommended Purpose Code list that indicates the type of Payment. This is optional for most payment types but recommended to be completed where possible; where it is required for certain purposes of CHAPS payment if not supplied a default value will be used

categoryOfPayment'BONU' | 'CASH' | 'CBLK' | 'CCRD' | 'CORT' | 'DCRD' | 'DIVI' | 'DVPM' | 'FCOL' | 'GP2P' | 'GOVT' | 'HEDG' | 'INTC' | 'INTE' | 'LOAN' | 'MP2P' | 'OTHR' | 'PENS' | 'RRCT' | 'SALA' | 'SECU' | 'SSBE' | 'SUPP' | 'TAXS' | 'TRAD' | 'TREA' | 'VATX' | 'WHLD'

A category code from the UK Recommended Purpose Code list that indicates the general category of the Payment. This is optional for all types of payment, and defaults to 'OTHR' on schemes that accept category

permittedScheme'SEPA_CREDIT_TRANSFER'

Attempt to process the payment using only the specified scheme

destinationIdstring
destinationType'BENEFICIARY' | 'ACCOUNT' | 'IBAN' | 'SCAN' | 'INTL' | 'ANBRN' | 'AN'

Example request

{
  "destination": {
    "type": "SCAN",
    "iban": "GB20MODR00000000000001",
    "accountNumber": "12345678",
    "sortCode": "000000",
    "name": "Test",
    "birthdate": "2000-01-01",
    "countrySpecificDetails": {
      "bankName": "Apple Bank",
      "bankAddress": "2100 Broadway",
      "bankCity": "New York City",
      "bankBranchName": "New York",
      "bankBranchCode": "44-04",
      "chineseId": "01101201901018889",
      "province": "Zhejiang",
      "abaRoutingNumber": "123456789",
      "business": true,
      "bankCodeType": "ABA",
      "bankCountry": "US"
    }
  },
  "reference": "Salary",
  "externalReference": "aReference_00001",
  "endToEndReference": "aReference_00001",
  "regulatoryReporting": {
    "type": "CRED",
    "regulatoryAuthority": {
      "authorityName": "Financial Conduct Authority",
      "authorityCountry": "GB"
    }
  },
  "paymentDate": "2017-01-28",
  "overseasPaymentDetail": {
    "ultimatePayer": {
      "address": {
        "addressLine1": "2nd Floor",
        "addressLine2": "123 High Street",
        "postTown": "Edinburgh",
        "postCode": "AB12 3XX",
        "country": "GB"
      },
      "birthDetails": {
        "dateOfBirth": "1978-01-01",
        "cityOfBirth": "Edinburgh",
        "countryOfBirth": "GB"
      },
      "officialIdentification": {
        "drivingLicenceNumber": "JONES849339TS8AD",
        "customerNumber": "23547326547632",
        "socialSecurityNumber": "1110000000022AB",
        "passportNumber": "123456789",
        "idCardNumber": "123456789",
        "otherIdNumber": "123456789"
      },
      "officialIdDetailOrgs": {
        "bankPartyIdentification": "12345",
        "centralBankIdNumber": "678910",
        "clearingIdNumber": "xx15402",
        "certificateOfIncorporationNumber": "1100010",
        "countryIdCode": "111111",
        "customerNumber": "00221133",
        "dataUniversalNumberingSystem": "002211330",
        "employerIdNumber": "00221133",
        "gs1glnIdentifier": "00221133",
        "sirenCode": "00221133",
        "siretCode": "00221133",
        "taxIdNumber": "00221133",
        "bicIdentifier": "MGALODJAO7A",
        "ibeiIdentifier": "HIZFTMTT59",
        "beiIdentifier": "MHIHISVZUMH",
        "eanglnIdentifier": "7516164953429",
        "chipsUniversalIdentifier": "CH157373",
        "genericIdentification3": "123456788",
        "genericIdentificationIssr": "13143225"
      },
      "overseasAccountIdentifier": {
        "iban": "GB20MODR00000000000001",
        "bban": "NWBK60161331926819",
        "upic": "987654321",
        "otherAccountNumber": "987654321"
      },
      "bic": "MODRDEFF123"
    },
    "chargeDetails": {
      "bearer": "CRED",
      "currency": "GBP"
    }
  },
  "nameCheck": {
    "id": "PAV2322342",
    "source": "MODULR"
  }
}

Response

PaymentReference

idstring required

Unique id for the Payment request. 10 characters long

status'SUBMITTED' | 'SCREENING_REQ' | 'VALIDATED' | 'PENDING_FOR_DATE' | 'PENDING_FOR_FUNDS' | 'EXT_PROC' | 'PROCESSED' | 'RECONCILED' | 'ER_INVALID' | 'ER_EXTCONN' | 'ER_EXTSYS' | 'ER_EXPIRED' | 'ER_GENERAL' | 'ER_BATCH' | 'EXT_SENT' | 'UNALLOCATED' | 'HELD' | 'RETURNED' | 'CANCELLED' | 'REPROCESSING' | 'VOID' | 'CLEARING' | 'HELD_IN_SUSPENSE' required

Current status of payment.

createdDatestring date-time

Datetime the request was created. Format is 'yyyy-MM-dd'T'HH:mm:ss.sssZ' where Z is UTC offset. e.g '2017-01-28T01:01:01.010+0000'

externalReferencestring required

external reference if provided

{"stackTrail":"components:schemas:payment.PaymentResponse:properties:details","oasType":"schema","type":"unknown","description":"All the details of the payment from the original request"}
approvalStatus'NOTNEEDED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'DELETED'

Current approval status of payment

messagestring

Information about payment (if available)

createdBystring

ID of the user that created the payment

type'PAYIN' | 'PAYOUT' | 'RETURN'
paymentScheduledDatestring date-time

Datetime of the payment scheduled at. Format is 'yyyy-MM-dd'T'HH:mm:ss.sssZ' where Z is UTC offset. e.g '2017-01-28T01:01:01.010+0000'

currentUserCanApproveboolean

Indicates if current user can approve the payment

Example response

{
  "id": "P000001ABC",
  "createdDate": "2017-01-28T01:01:01.010+0000",
  "externalReference": "aReference_00001",
  "paymentScheduledDate": "2017-01-28T01:01:01.010+0000",
  "approvals": [
    {
      "approvedBy": "U2100021",
      "approvedOn": "2022-06-25"
    }
  ]
}