Step 1: Initiate Outbound Request-To-Pay

Overview

An account holder at your bank sends an outbound request-to-pay to prompt a payer, or debtor, at an industry bank to credit their account. If the debtor (i.e., the industry participant's customer) agrees, an inboundCreditTransfer operation will be performed to credit the account. If the industry participant or operator rejects the request, then this will be communicated to you via an outboundRequestToPayResponse operation.

The industry scheme may require a confirmation that the payment request will be presented to the payer. In this case, the confirmation is communicated to you by way of an outboundRequestToPayResponse operation.

Implementing the API

Send Request-To-Pay Request

Send an outboundRequestToPay request to Electrum's /transactions/outbound/request-to-pay endpoint.

The full message schema can be found in the API reference documentation. Code and payload samples are shown below.

curl -i -X POST \
  https://example.com/path/payments/api/v1/transactions/outbound/request-to-pay \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "paymentScheme": {
      "schema": "ZA_RPP"
    },
    "amounts": {
      "bankSettlementAmount": {
        "value": 100,
        "currency": "ZAR"
      }
    },
    "paymentTypeInformation": {
      "localInstrument": {
        "schema": "PROPRIETARY",
        "value": "PBPX"
      }
    },
    "expiryDateTime": "2024-04-09T09:32:51.395+02:00",
    "requestToPayConditions": {
      "minAmount": {
        "value": 100,
        "currency": "ZAR"
      },
      "maxAmount": {
        "value": 100,
        "currency": "ZAR"
      }
    },
    "creditor": {
      "address": {
        "addressType": "ADDR",
        "department": "Department of Mysteries",
        "streetName": "Street of Mysteries",
        "buildingNumber": "42",
        "buildingName": "Mysterious Building",
        "floor": "42",
        "postBox": "1024",
        "postCode": "4242",
        "townName": "Mysty Town",
        "townLocationName": "Mysty Location",
        "districtName": "Mysty District",
        "countrySubDivision": "Mysterious Cape",
        "country": "ZA",
        "addressLine": [
          "16A",
          "New market street",
          "Foreshore",
          "Cape Town",
          "ZA",
          "8001"
        ]
      },
      "contactDetails": {
        "phoneNumber": "+27-0214620000",
        "mobileNumber": "+27-08230000000",
        "emailAddress": "developer.dave@electrum.com"
      },
      "countryOfResidence": "ZA",
      "identification": {
        "schema": "PERSON",
        "identifiers": [
          {
            "identification": "90001236549870",
            "scheme": {
              "schema": "CODE",
              "value": "NIDN"
            },
            "issuer": "Dept of Home Affairs"
          }
        ]
      }
    },
    "creditorAccount": {
      "identification": {
        "schema": "GENERIC",
        "scheme": {
          "schema": "PROPRIETARY",
          "value": "AProprietaryCode123"
        },
        "issuer": "Amazing Bank",
        "value": "abcdef987654"
      },
      "type": {
        "schema": "CODE",
        "value": "CACC"
      },
      "currency": "ZAR"
    },
    "creditorAgent": {
      "bicfi": "RY8PEG0L",
      "memberId": "AmazingBankId",
      "name": "Amazing Bank Inc",
      "branch": {
        "identification": "210514",
        "name": "ABC Plettenberg Bay",
        "address": {
          "addressType": "ADDR",
          "department": "Department of Mysteries",
          "streetName": "Street of Mysteries",
          "buildingNumber": "42",
          "buildingName": "Mysterious Building",
          "floor": "42",
          "postBox": "1024",
          "postCode": "4242",
          "townName": "Mysty Town",
          "townLocationName": "Mysty Location",
          "districtName": "Mysty District",
          "countrySubDivision": "Mysterious Cape",
          "country": "ZA",
          "addressLine": [
            "16A",
            "New market street",
            "Foreshore",
            "Cape Town",
            "ZA",
            "8001"
          ]
        }
      }
    },
    "ultimateCreditor": {
      "address": {
        "addressType": "ADDR",
        "department": "Department of Mysteries",
        "streetName": "Street of Mysteries",
        "buildingNumber": "42",
        "buildingName": "Mysterious Building",
        "floor": "42",
        "postBox": "1024",
        "postCode": "4242",
        "townName": "Mysty Town",
        "townLocationName": "Mysty Location",
        "districtName": "Mysty District",
        "countrySubDivision": "Mysterious Cape",
        "country": "ZA",
        "addressLine": [
          "16A",
          "New market street",
          "Foreshore",
          "Cape Town",
          "ZA",
          "8001"
        ]
      },
      "contactDetails": {
        "phoneNumber": "+27-0214620000",
        "mobileNumber": "+27-08230000000",
        "emailAddress": "developer.dave@electrum.com"
      },
      "countryOfResidence": "ZA",
      "identification": {
        "schema": "PERSON",
        "identifiers": [
          {
            "identification": "90001236549870",
            "scheme": {
              "schema": "CODE",
              "value": "NIDN"
            },
            "issuer": "Dept of Home Affairs"
          }
        ]
      }
    },
    "debtor": {
      "address": {
        "addressType": "ADDR",
        "department": "Department of Mysteries",
        "streetName": "Street of Mysteries",
        "buildingNumber": "42",
        "buildingName": "Mysterious Building",
        "floor": "42",
        "postBox": "1024",
        "postCode": "4242",
        "townName": "Mysty Town",
        "townLocationName": "Mysty Location",
        "districtName": "Mysty District",
        "countrySubDivision": "Mysterious Cape",
        "country": "ZA",
        "addressLine": [
          "16A",
          "New market street",
          "Foreshore",
          "Cape Town",
          "ZA",
          "8001"
        ]
      },
      "contactDetails": {
        "phoneNumber": "+27-0214620000",
        "mobileNumber": "+27-08230000000",
        "emailAddress": "developer.dave@electrum.com"
      },
      "countryOfResidence": "ZA",
      "identification": {
        "schema": "PERSON",
        "identifiers": [
          {
            "identification": "90001236549870",
            "scheme": {
              "schema": "CODE",
              "value": "NIDN"
            },
            "issuer": "Dept of Home Affairs"
          }
        ]
      }
    },
    "debtorAccount": {
      "proxy": {
        "schema": "MOBILE",
        "value": "+27-721234567",
        "namespace": "amazebank"
      },
      "type": {
        "schema": "CODE",
        "value": "CACC"
      },
      "currency": "ZAR"
    },
    "debtorAgent": {
      "bicfi": "RY8PEG0L",
      "memberId": "AmazingBankId",
      "name": "Amazing Bank Inc",
      "branch": {
        "identification": "210514",
        "name": "ABC Plettenberg Bay",
        "address": {
          "addressType": "ADDR",
          "department": "Department of Mysteries",
          "streetName": "Street of Mysteries",
          "buildingNumber": "42",
          "buildingName": "Mysterious Building",
          "floor": "42",
          "postBox": "1024",
          "postCode": "4242",
          "townName": "Mysty Town",
          "townLocationName": "Mysty Location",
          "districtName": "Mysty District",
          "countrySubDivision": "Mysterious Cape",
          "country": "ZA",
          "addressLine": [
            "16A",
            "New market street",
            "Foreshore",
            "Cape Town",
            "ZA",
            "8001"
          ]
        }
      }
    },
    "ultimateDebtor": {
      "address": {
        "addressType": "ADDR",
        "department": "Department of Mysteries",
        "streetName": "Street of Mysteries",
        "buildingNumber": "42",
        "buildingName": "Mysterious Building",
        "floor": "42",
        "postBox": "1024",
        "postCode": "4242",
        "townName": "Mysty Town",
        "townLocationName": "Mysty Location",
        "districtName": "Mysty District",
        "countrySubDivision": "Mysterious Cape",
        "country": "ZA",
        "addressLine": [
          "16A",
          "New market street",
          "Foreshore",
          "Cape Town",
          "ZA",
          "8001"
        ]
      },
      "contactDetails": {
        "phoneNumber": "+27-0214620000",
        "mobileNumber": "+27-08230000000",
        "emailAddress": "developer.dave@electrum.com"
      },
      "countryOfResidence": "ZA",
      "identification": {
        "schema": "PERSON",
        "identifiers": [
          {
            "identification": "90001236549870",
            "scheme": {
              "schema": "CODE",
              "value": "NIDN"
            },
            "issuer": "Dept of Home Affairs"
          }
        ]
      }
    },
    "instructedAgent": {
      "bicfi": "RY8PEG0L",
      "memberId": "AmazingBankId",
      "name": "Amazing Bank Inc",
      "branch": {
        "identification": "210514",
        "name": "ABC Plettenberg Bay",
        "address": {
          "addressType": "ADDR",
          "department": "Department of Mysteries",
          "streetName": "Street of Mysteries",
          "buildingNumber": "42",
          "buildingName": "Mysterious Building",
          "floor": "42",
          "postBox": "1024",
          "postCode": "4242",
          "townName": "Mysty Town",
          "townLocationName": "Mysty Location",
          "districtName": "Mysty District",
          "countrySubDivision": "Mysterious Cape",
          "country": "ZA",
          "addressLine": [
            "16A",
            "New market street",
            "Foreshore",
            "Cape Town",
            "ZA",
            "8001"
          ]
        }
      }
    },
    "instructingAgent": {
      "bicfi": "RY8PEG0L",
      "memberId": "AmazingBankId",
      "name": "Amazing Bank Inc",
      "branch": {
        "identification": "210514",
        "name": "ABC Plettenberg Bay",
        "address": {
          "addressType": "ADDR",
          "department": "Department of Mysteries",
          "streetName": "Street of Mysteries",
          "buildingNumber": "42",
          "buildingName": "Mysterious Building",
          "floor": "42",
          "postBox": "1024",
          "postCode": "4242",
          "townName": "Mysty Town",
          "townLocationName": "Mysty Location",
          "districtName": "Mysty District",
          "countrySubDivision": "Mysterious Cape",
          "country": "ZA",
          "addressLine": [
            "16A",
            "New market street",
            "Foreshore",
            "Cape Town",
            "ZA",
            "8001"
          ]
        }
      }
    },
    "remittanceInformation": {
      "unstructured": [
        "some",
        "unstructured",
        "information"
      ],
      "structured": [
        {
          "creditorReference": {
            "reference": "ABC123XYZ999"
          },
          "additionalRemittanceInformation": [
            "Some",
            "Additional",
            "Information"
          ]
        }
      ]
    },
    "schema": "RequestToPay",
    "messageIdentifiers": {
      "messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
      "creationDateTime": "2022-05-04T03:02:01Z"
    },
    "transactionIdentifiers": {
      "endToEndIdentification": "6249118655591098",
      "transactionIdentification": "RRN000000001",
      "uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa"
    }
  }'

Response

No content

Receive Acknowledgement

Electrum will respond with an HTTP 202 status if the request can be processed successfully, or an error response if a problem occurs.

Timeout

If you don't receive any response from Electrum — this may happen because of a networking issue or other technical error — then you may retry the request. The recommended procedure is to retry the operation with the same payload up to 3 times at 1 second intervals, until you receive a 202 response.

Idempotency

The outboundRequestToPay operation is idempotent. This means it is safe for you to send retries. If Electrum has already received the original message, then a retry of the same message will be recognised as a duplicate and will not affect the processing of the transaction.