OpenPayd Developer Hub

Welcome to the OpenPayd developer hub. You'll find comprehensive guides and documentation to help you start working with OpenPayd as quickly as possible, as well as support if you get stuck. Let's jump right in!

API Reference    Guides

SEPA Direct Debits (Alpha)

SEPA Direct Debits can be setup on OpenPayd EUR Accounts. This allows users to have direct debits for utility bills, mortgages etc. to be collected from their OpenPayd Accounts.

Direct Debit Collection Request

A webhook notification will be sent whenever a Direct Debit request is received on an Account as part of a new or existing Direct Debit Mandate.

The notification contains details of the Direct Debit Mandate, amount, due date and cut-off time.

{
   "transactionId":"17218a31-bfd2-4482-92f8-2061e11dcefe",
   "status":"PENDING",
   "accountHolderId":"de5c35ea-584b-4eed-9573-651224416a9b",
   "accountId":"RnVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
   "mandate":{
      "id":"FWVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
      "dateOfSigning":"2020-11-12",
      "status":"ACTIVE",
      "creditor":{
         "id":"MeVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
         "mandateReference":"b5a2b6b7-a867-4ec7-8bdc-1009306a9d25",
         "accountId":"RnVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
         "name":"Yavor",
         "addressLine1":"Yavor’s home street",
         "addressLine2":"street 37",
         "country":"GB",
         "bic":"TTBBBG22",
         "iban":"GB46BARC20031852436423",
         "institutionId":"bNAIASOPDNAOP1NDONJ1ODMNALDAMDHDLDN",
         "type":"BUSINESS"
      }
   },
   "debitType":"FIRST",
   "amount":{
      "value":10,
      "currency":"EUR"
   },
   "fee":{
      "value":1,
      "currency":"EUR"
   },
   "totalAmount":{
      "value":11,
      "currency":"EUR"
   },
   "dueDate":"2020-12-15T10:15:30",
   "cutOffTime":"2020-12-15T04:00:00",
   "transactionReference":"Test"
}

The notification can be for several debit types contained in the debitType param:

  1. FIRST - The first notification for a new direct debit mandate
  2. RECURRING - A new collection request for an existing direct debit mandate
  3. FINAL - The final collection request for an existing direct debit mandate
  4. ONE_OFF - A one off collection request

The cutOffTtime indicates the time before which a Direct Debit collection request can be rejected.

Direct Debit Review

If no action is taken upon receiving a webhook notification for a Direct Debit Collection, funds will be reserved on the Account at the cutOffTtime and will be debited at the dueDate.

A Direct Debit Collection can be rejected by the user before the cutOffTtime.

Rejecting a Direct Debit Collection

curl --location --reques POST '/transactions/direct-debit/review' \
--header 'X-ACCOUNT-HOLDER-ID: 6d4a0db6-8e13-474a-b51b-0f0ef3e2869c' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
    "transactionId": "118fec52-d741-4a3c-b500-27a13ee498c6",
    "decision": "REJECTED",
    "reason": "NOT_SPECIFIED"
}'
  • transactionId - The transactionId from the Direct Debit Collection webhook
  • reason - DECEASED, NOT_SPECIFIED
  • Error Codes - DIRECT_DEBIT_ALREADY_REJECTED, CUT_OFF_TIME_PASSED

Direct Debit Transaction

If a Direct Debit Collection was not rejected, the amount will be debited from the account at the dueDate and a new transaction of type DIRECT_DEBIT will be created on the account.

A Transaction Status Updated webhook will be sent when the direct debit transaction is completed.

{
   "id":"Qm5TOTRxcmhxK2pnZHpzeDZPZHBRZz09",
   "shortId":"20200803-8EFH4W",
   "accountId":"cWc4SktyWlkxM0hwcmdYe6FMdXRSQT09",
   "createdDate":"2020-08-03T13:16:22.700Z",
   "updatedDate":"2020-08-03T13:16:22.700Z",
   "transactionId":"4b5ea64c-cf39-403a-a887-303b66794a92",
   "transactionCategory":"OTHER",
   "paymentType":"SEPA",
   "type":"DIRECT_DEBIT",
   "status":"COMPLETED",
   "accountHolderId":"6d4a0db6-8e13-474a-b51b-0f0ef3e2869c",
   "sourceInfo":{
      "type":"ACCOUNT",
      "identifier":"cWc4SktyWlkxM0hwcmdYe6FMdXRSQT09",
      "internalAccountId":"EUR08561376339076"
   },
   "destinationInfo":{
      "type":"DIRECT_DEBIT_MANDATE",
      "identifier":"UmQwZ1IxWTdGRy9Ob1IvYVdDMFZ3dz09"
   },
   "source":null,
   "destination":"EUR20011679626470",
   "fxRate":null,
   "midMarketRate":null,
   "fixedSide":null,
   "totalAmount":{
      "value":-11,
      "currency":"EUR"
   },
   "amount":{
      "value":-10,
      "currency":"EUR"
   },
   "buyAmount":null,
   "fee":{
      "value":-1,
      "currency":"EUR"
   },
   "runningBalance":{
      "value":9929.00,
      "currency":"EUR"
   },
   "failureReason":null,
   "comment":null,
   "transactionReference":"Bill Payment",
   "referenceAmount":null,
   "createdBy":"SYSTEM",
   "checkedBy":null,
   "checkedDate":null,
   "originalTransactionId":null
}

Refunds

As per SEPA Direct Debit scheme rules, customers have a no questions asked right to receive a refund for up to eight weeks after the debit of their account. In the case of unauthorised transactions, the period is extended to 13 months after the due date.

Requesting a Direct Debit Refund

curl --location --reques POST '/transactions/direct-debit/refund' \
--header 'X-ACCOUNT-HOLDER-ID: 6d4a0db6-8e13-474a-b51b-0f0ef3e2869c' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
    "transactionId": "aWQvdy90VU5SYTdaSCtQa2lPWGhXUT09",
    "reason": "NOT_SPECIFIED"
}'

Once a refund has been processed by the creditor institution that collected the direct debit, the transaction will appear on the account as a DIRECT_DEBIT_REFUND which will also be notified via a webhook event. The DIRECT_DEBIT_REFUND will have the id of the original transaction for which the refund was requested in the originalTransactionId param.

{
   "id":"Qm5TOTRxcmhxK2pnZHpzeDZPZHBRZz09",
   "shortId":"20201012-9ABC5Z",
   "accountId":"Y2V4YndseHQybldDWFRCQnplZzUvdz09",
   "createdDate":"2020-10-12T13:16:22.700Z",
   "updatedDate":"2020-10-12T13:16:22.700Z",
   "transactionId":"dcda9ae1-bbda-4077-96ce-d44a5560f696",
   "transactionCategory":"OTHER",
   "paymentType":null,
   "type":"RETURN_IN",
   "status":"COMPLETED",
   "accountHolderId":"6d4a0db6-8e13-474a-b51b-0f0ef3e2869c",
   "sourceInfo":{
      "type":"DIRECT_DEBIT_MANDATE",
      "identifier":"NFhZRjJsSmFLZnRSa2dJVk9uRFN0dz09"
   },
   "destinationInfo":{
      "type":"ACCOUNT",
      "identifier":"bXBYcWt1STJQZnNxK1dxeWtxVlNwdz09",
      "internalAccountId":"EUR20011679626470"
   },
   "source":null,
   "destination":"EUR20011679626470",
   "fxRate":null,
   "midMarketRate":null,
   "fixedSide":null,
   "totalAmount":{
      "value":10,
      "currency":"EUR"
   },
   "amount":{
      "value":10,
      "currency":"EUR"
   },
   "buyAmount":null,
   "fee":{
      "value":0,
      "currency":"EUR"
   },
   "runningBalance":{
      "value":9939,
      "currency":"EUR"
   },
   "failureReason":null,
   "comment":null,
   "transactionReference":"Bill Payment",
   "referenceAmount":null,
   "createdBy":"SYSTEM",
   "checkedBy":null,
   "checkedDate":null,
   "originalTransactionId":"9fb21f6a-a214-4969-97ac-9b46a7e420b0",
}

Reversals

It may happen that a direct debit is reversed by the creditor after it has already been collected. For e.g. because the creditor collected an incorrect amount.

In this scenario, a RETURN_IN transaction will appear on the account which will also be notified via a webhook event. The RETURN_IN will have the id of the original transaction that was reversed in the originalTransactionId param.

{
   "id":"Qm5TOTRxcmhxK2pnZHpzeDZPZHBRZz09",
   "shortId":"20201012-9ABC5Z",
   "accountId":"Y2V4YndseHQybldDWFRCQnplZzUvdz09",
   "createdDate":"2020-10-12T13:16:22.700Z",
   "updatedDate":"2020-10-12T13:16:22.700Z",
   "transactionId":"dcda9ae1-bbda-4077-96ce-d44a5560f696",
   "transactionCategory":"OTHER",
   "paymentType":null,
   "type":"RETURN_IN",
   "status":"COMPLETED",
   "accountHolderId":"6d4a0db6-8e13-474a-b51b-0f0ef3e2869c",
   "sourceInfo":{
      "type":"DIRECT_DEBIT_MANDATE",
      "identifier":"NFhZRjJsSmFLZnRSa2dJVk9uRFN0dz09"
   },
   "destinationInfo":{
      "type":"ACCOUNT",
      "identifier":"bXBYcWt1STJQZnNxK1dxeWtxVlNwdz09",
      "internalAccountId":"EUR20011679626470"
   },
   "source":null,
   "destination":"EUR20011679626470",
   "fxRate":null,
   "midMarketRate":null,
   "fixedSide":null,
   "totalAmount":{
      "value":10,
      "currency":"EUR"
   },
   "amount":{
      "value":10,
      "currency":"EUR"
   },
   "buyAmount":null,
   "fee":{
      "value":0,
      "currency":"EUR"
   },
   "runningBalance":{
      "value":9939,
      "currency":"EUR"
   },
   "failureReason":null,
   "comment":null,
   "transactionReference":"Bill Payment",
   "referenceAmount":null,
   "createdBy":"SYSTEM",
   "checkedBy":null,
   "checkedDate":null,
   "originalTransactionId":"9fb21f6a-a214-4969-97ac-9b46a7e420b0",
}

Mandate Status Updated

A webhook notification will be sent when an existing direct debit mandate is CANCELLED by a creditor, or the last transaction (debitType = FINAL or ONE_OFF) has been collected and therefore the direct debit mandate is COMPLETED.

{
   "accountHolderId":"de5c35ea-584b-4eed-9573-651224416a9b",
   "accountId":"RnVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
   "mandate":{
      "id":"FWVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
      "mandateReference": "8e75e511-b90a-4a62-abf8-6c0d9d1baf10",
      "accountId": "OUdrM1pNei8xK1hnMjBGMnQ0UVIrQT09",
      "dateOfSigning":"2020-11-12",
      "status":"COMPLETED",
      "creditor":{
         "id":"MeVtcmVVVEJDVEd4T3VsenhaU0VmZz09",
         "name":"Yavor",
         "addressLine1":"Yavor’s home street",
         "addressLine2":"street 37",
         "country":"GB",
         "bic":"TTBBBG22",
         "iban":"GB46BARC20031852436423",
         "institutionId":"bNAIASOPDNAOP1NDONJ1ODMNALDAMDHDLDN",
         "type":"BUSINESS"
      }
   }
}

status - ACTIVE, CANCELLED, COMPLETED

Updated 10 days ago

SEPA Direct Debits (Alpha)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.