Step 1: Initiate Outbound PayShap Refund

Overview

If one of your account holders has been credited as a result of an outbound request-to-pay to a customer at an industry bank, but now wishes to refund that credited amount back to the payer, then your account holder can initiate an outbound refund. You make an asynchronous request to Electrum. Electrum will immediately acknowledge receipt of the request and then initiate a sequence of calls to the payment scheme in order to process the transaction.

When to debit funds

It is important that you debit your customer's account before sending the refund initiation request to Electrum. This will ensure that the customer has sufficient funds to cover the transaction. If the transaction is declined for any reason, then you may credit the funds back to the account.

Implementing the API

Send Outbound Refund Initiation

Send an outboundRefundInitiation request to Electrum's /transactions/outbound/refund-initiation 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/refund-initiation \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "amounts": {
      "bankSettlementAmount": {
        "value": 50,
        "currency": "ZAR"
      },
      "instructedAmount": {
        "value": 50,
        "currency": "ZAR"
      }
    },
    "debtorAccount": {
      "identification": {
        "schema": "GENERIC",
        "scheme": {
          "schema": "PROPRIETARY",
          "value": "AProprietaryCode123"
        },
        "issuer": "Amazing Bank",
        "value": "abcdef987654"
      },
      "type": {
        "schema": "CODE",
        "value": "CACC"
      }
    },
    "schema": "RefundInitiationRequest",
    "messageIdentifiers": {
      "messageIdentification": "9fd51c7124ba4819b9253e296a6be1da",
      "creationDateTime": "2022-05-04T03:02:01Z"
    },
    "transactionIdentifiers": {
      "endToEndIdentification": "5129118655591098",
      "transactionIdentification": "RRN000000002",
      "uetr": "9f7a56ad-c5ab-4b70-a3f9-946d743eaeaa"
    },
    "originalTransactionIdentifiers": {
      "endToEndIdentification": "6249118655591098",
      "transactionIdentification": "RRN000000001",
      "uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa"
    },
    "paymentScheme": {
      "schema": "ZA_RPP",
      "schemeData": {
        "hasRtp": true
      }
    }
  }'

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 outboundRefundInitiation operation is idempotent. This means it is safe for you to send retries, i.e., multiple instances of the same message. 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.