Local Payment Verification Endpoint
Context
PAPE at its core enables cross-border payment between any two financial institutions. Keyword here is cross-border.
For practical and regulatory purposes, not all financial institutions will be designated applicable to handle the huge amount of funds brought in by liquidity providers.
To enable even the smaller financial institutions participate in cross-border payments, it is important to distinguish between two types of financial institutions.
Liquidity Gateways: Or gateways for short. These are the big multinational banks who will be designated to hold liquidity on behalf of liquidity providers for each country.Non Liquidity Gateways: Or PSP (payment service providers) for short. These are the banks, microfinances and fintechs that are plugged into thePAPEnetwork, but cannot hold liquidity on behalf of liquidity providers.
Here’s a sample cross-border payment workflow between Country A and Country B.
PAPE Sequence Diagram
The local payment verification endpoint.
This represents arrow 10 in the sequence diagram above.
This endpoint has to be implemented by Liquidity Gateways in PAPE.
The endpoint is a GET request, and will have the following query parameters:
Confirm or reject local payment from other local financial institutions.
payment_channel=string: Is the preapproved local payment channel to be used for local payments. A special value of local is reserved for payments within the same bank.transaction_reference=string: The transaction reference returned by the local payment channel used after a successful local payment. This value has to be unique for every payment channel.amount=string: A string parameter which specifies the amount involved without fees in the local payment.currency=string: A string parameter which specifies the currency involved in the local payment.https://url_of_local_payment_verification_endpoint?
payment_channel={payment_channel}
transaction_reference={transaction_reference}
&amount={amount}
¤cy={currency}
A successful local payment verification will return an HTTP code 200 :
In case of an error, the local payment verification service should return a non-200 HTTP code, with the following json:
{
"error": "summary error message"
}
Security
For extra security, all requests will include a Bearer Authorization header, with a bearer token supplied to PAPE during onboarding. All account verification endpoints should be served through HTTPS to reduce the risk of leaking this Bearer token.
It is important to note that the payment gateway will be the one to supply us the appropriate Bearer token to use. Ideally a non-expiring JWT token.