Honor Crossborder Payments

Learn how to honor crossborder payments.

Overview

In the previous tutorial, you learned how you, the Payment Gateway, can acknowledge fund deposits for cross-border payments on behalf of your users.

End users in other financial institutions may wish to send funds that terminate in your financial institution. It is your job, you the financial institution PAPE integrator, to honor those payment requests.

You do that by checking all pending PAPE payments that terminate into your financial institution. The relevant APIs are found below. Once you’ve found pending payments requests, you process them within your own backend.

NB: Crossborder terminating requests DO NOT get pushed to you the integrator. You will have to continuously POLL the payments endpoint to find new payment requests for you to process.

Gateway Statuses

Possible values are:

  • pending
  • processed
  • error
  • reverted

Data Models

Payment

fieldtypedescription
senderGatewayIdstringPayment Gateway ID of the sender
senderCurrencystringCurrency used by the sender
senderAccountstringSender account
receiverGatewayIdstringPayment Gateway ID of the receiver
receiverAccountstringReceiver account
receiverCurrencystringCurrency used by the receiver
receiverAmountstringAmount in receiver currency the destination will receive
memostringmemo associated with the payment
senderAmountstringAmount sender has to pay, excluding sender fees
senderNamestringName of the sender
receiverNamestringName of the receiver
receivingGatewayFeestringAmount in receiver currency charged by the receiving gateway
senderGatewayTransactionIdstringTransaction id generated by the sending gateway when sending a payment
receiverGatewayTransactionIdstringTransaction id generated by the receiving gateway when honoring a payment
senderGatewayStatusstringStatus of the payment according to the sending gateway
receiverGatewayStatusstringStatus of the payment according to the receiving gateway
blockchainTransactionIdstringBlockchain transaction ID of the payment

Payments - API Calls

Get pending payments

Confirm processed payment

Try it out:

Let’s get a list of pending payments requests and confirm one payment.

Tools you might need

These are the tools you might need to follow along this tutorial.

  • linux or mac: Many of the command line examples have been customized for UNIX-like operating systems.

  • curl: To perform API calls.

    • mac: brew install curl
    • ubuntu/debian: sudo apt-get install curl

  • jq: To process json on the command line.

    • mac: brew install jq
    • ubuntu/debian: sudo apt-get install jq

  • jo: To create json on the command line.

    • mac: brew install jo
    • ubuntu/debian: sudo apt-get install jo

  • openssl: To perform cryptographic operations on the command line.

    • mac: brew install openssl
    • ubuntu/debian: sudo apt-get install openssl

Get Token

export PAPE_TOKEN_ENDPOINT=https://id.dev.projectwhite.io/auth/realms/projectwhite/protocol/openid-connect/token;

export PAPE_API_ENDPOINT=https://apis-alpha.dev.projectwhite.io

export PAPE_USERNAME=cm.wallet.interstellar-demo.xaf;

export PAPE_PASSWORD=abc;

export PAPE_TOKEN=`curl -s --request POST \
--url "$PAPE_TOKEN_ENDPOINT" \
--data-urlencode grant_type=password \
--data-urlencode username=$PAPE_USERNAME \
--data-urlencode password=$PAPE_PASSWORD \
--data-urlencode 'client_id=projectwhite' \
| jq -r ".access_token"`

echo $PAPE_TOKEN

Get pending payments


curl --request GET \
  --url "$PAPE_API_ENDPOINT/payments?receiverProcessingGatewayId=cm.wallet.interstellar-demo.xaf&receiverGatewayStatus=pending" \
  --header "Authorization: Bearer $PAPE_TOKEN" | jq .

Sample Response

[
  {
    "id": "ae5894c2c97738b01b5865a3b357bb8bab4b5535d649bdca6f055a122c4598b9",
    "createdAt": "2021-10-11T13:26:50.962Z",
    "updatedAt": "2021-10-11T13:26:50.962Z",
    "pagingToken": "1633958810962-2395471023",
    "senderGatewayId": "gh.wallet.expresspay.ghs",
    "senderAmount": "780",
    "senderCurrency": "GHS",
    "senderAccount": "233243722297",
    "senderName": "Isa Frimpong",
    "receiverGatewayId": "cm.wallet.interstellar-demo.xaf",
    "receiverProcessingGatewayId": "cm.wallet.interstellar-demo.xaf",
    "receiverAmount": "1200",
    "receiverCurrency": "XAF",
    "receiverAccount": "225345654334",
    "receiverName": "Interstellar XAF 12345",
    "senderGatewayStatus": "processed",
    "receiverGatewayStatus": "pending",
    "senderGatewayTransactionId": "test_trf_00001",
    "receiverGatewayTransactionId": "",
    "senderGatewayPublicKey": "",
    "receiverGatewayPublicKey": "",
    "blockchainTransactionId": "1592160e86810cd8b7caca774c2cb016c8009ee3031e68321018afd5c1277c69",
    "receivingGatewayFee": "100",
    "memo": "",
    "creationRequestUrl": "/payments",
    "creationRequestBody": "{\"senderGatewayId\":\"gh.wallet.expresspay.ghs\",\"senderAmount\":\"780\",\"senderCurrency\":\"GHS\",\"senderAccount\":\"233243722297\",\"senderName\":\"Isa Frimpong\",\"receiverGatewayId\":\"cm.wallet.interstellar-demo.xaf\",\"receiverAmount\":\"1200\",\"receiverCurrency\":\"XAF\",\"receiverAccount\":\"225345654334\",\"receiverName\":\"Interstellar XAF 12345\",\"receivingGatewayFee\":\"100\",\"extras\":null,\"senderGatewayTransactionId\":\"test_trf_00001\"}",
    "creationRequestPublicKeyBase64": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUFybWxvbktlS0U3bmY2L2FYS2lRNQpDVFErdlgzWWE4b2FWbDdqN3I4Wld2QjR2K0dsU3ZpOG96ZFVKeGZtVFdROUN1dUNwT2p3SnBmRmk5YWVBRm5pClFJdlhXK1pqdjBqcjVncmEwSUt3SnNjVnNod3N6TGlnQVUyQVprcXV0Q2NVdFFnajgzWDNLNnhHaHpaSXRvYWIKYjVQRXhBQlFuQzNJUFBKRno3ZW8zRlRCM2wyQ2FjZkJ6MkNOOFM4S251VVhiR0VwODdMbmlPaUlWalVzdStsNQpxZWIzUjhjeWhSVHd2R203YzdGNklqaEF6SXRPSWtZdHlDbm1lQ3pNMjRJamZKZG5KZ2JETERoeitrR0Z0OGo2Ck01Vml0RHpiOWtDT2h3UDNYSklJTUdSNFFSQU93Z3AvRXhkZmhZaERwNDJoYjZESitWUzR6ZGIwTS9hVnl5c1UKYndJREFRQUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==",
    "creationRequestSignatureBase64": "lLmSi2NDXNS1M22K1/cBVxY2+Xo9UtpVA0xasQNP60T8ll8JY6VWnp0n8suyvyH7qplJOToD3/hr/INbgWzoXk9JxI1hIjQDh9hNvu/ACDrZsLKv7yM1E4iHPfxXVPNEnZlRtYuDmW8BPN0goY2td+k+WnGT05dZUkhqXHVjumgykWoT5ZBNMHiZ1G8mdmSz6H6W6v6OAtP6RXvZPv8f/kTIr9+DRvqgonxYwBwlgJM3rM2LSF6z781jMUP3PNFNlaaic1IbzqUY9WJI8HF8w3rEvMdTTw1KmjGGwAhp8TeCCCVR/TSoR/hwqXg2nNIrhNSlJeKwyeIZnt8mJwWRwg==",
    "extras": null
  }

]

Confirm processed payment on receiver gateway

Let’s confirm the previous payment ID has been processed on the receiving gateway.

export PAYMENT_ID=ae5894c2c97738b01b5865a3b357bb8bab4b5535d649bdca6f055a122c4598b9

curl --request PUT \
  --url $PAPE_API_ENDPOINT/payments/$PAYMENT_ID \
  --header "Authorization: Bearer $PAPE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "receiverGatewayTransactionId": "'$(date +%s)'",
  "receiverGatewayStatus": "processed"
}'

Withdrawal List APIs

curl --request GET \
  --url 'https://apis-alpha.dev.projectwhite.io/payments?receiverProcessingGatewayId=string&receiverGatewayStatus=pending'
← Send Cross Border Payments
Create New Payment Gateway →