| Table of Contents | ||||
|---|---|---|---|---|
|
1. Overview
The International Payments resource is used by a PISP to initiate an International Payment.
This resource description should be read in conjunction with a compatible Payment Initiation API Profile.
2. Endpoints
Endpoints for the resource - and available methods.
S. No. | Resource | HTTP Operation | Endpoint | Mandatory ? | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
2.1 | international-payments | POST | POST /international-payments | Conditional | payments | Authorisation Code | Signed Request Signed Response | Yes | OBWriteInternational | OBWriteInternationalPaymentResponse |
2.2 | international-payments | GET | GET /international-payments/{InternationalPaymentId} | Mandatory (if resource POST implemented) | payments | Client Credentials | Signed Response | No | NA | OBWriteInternationaPaymentlResponse |
2.3 | payment-details | GET | GET /international-payments/{InternationalPaymentId}/payment-details | Optional | payments | Client Credentials | Signed Response | No | NA | OBWritePaymentDetailsResponse |
2.1 1 POST/international-payments
Once the international-payment-consent has been authorised by the PSU, the PISP can proceed to submit the international-payment for processing:
This is done by making a POST request to the international-payments endpoint.
This request is an instruction to the ASPSP to begin the international single immediate payment journey. The international payment must be submitted immediately, however, there are some scenarios where the international payment may not be executed immediately (e.g. busy periods at the ASPSP).
The PISP must ensure that the Initiation and Risk sections of the international-payment match the corresponding Initiation and Risk sections of the international-payment-consent resource. If the two do not match, the ASPSP must not process the request and must respond with a 400 (Bad Request).
Any operations on the international-payment resource will not result in a Status change for the international-payment resource.
2.1.1 Status1 Status
An international-payment can only be created if its corresponding international-payment-consent resource has the status of "Authorised".
...
Status |
Pending |
Rejected |
AcceptedSettlementInProcess |
AcceptedSettlementCompleted |
AcceptedWithoutPosting |
AcceptedCreditSettlementCompleted |
2.2 2 GET /international-payments/{InternationalPaymentId}
A PISP can retrieve the international-payment to check its status.
2.2.1 1 Status
The international-payment resource must have one of the following PaymentStatusCode code-set enumerations:
Status |
Pending |
Rejected |
AcceptedSettlementInProcess |
AcceptedSettlementCompleted |
AcceptedWithoutPosting |
AcceptedCreditSettlementComplete |
22.3 3 GET /international-payments /{InternationalPaymentId}/payment-details
A PISP can retrieve the Details of the underlying payment transaction via this endpoint. This resource allows ASPSPs to return richer list of Payment Statuses, and if available payment scheme related statuses.
2.3.1 Status1 Status
The international-payments - payment-details must have one of the following PaymentStatusCode code-set enumerations:
Status |
Accepted |
AcceptedCancellationRequest |
AcceptedTechnicalValidation |
AcceptedCustomerProfile |
AcceptedFundsChecked |
AcceptedWithChange |
Pending |
Rejected |
AcceptedSettlementInProcess |
AcceptedSettlementCompleted |
AcceptedWithoutPosting |
AcceptedCreditSettlementCompleted |
Cancelled |
NoCancellationProcess |
PartiallyAcceptedCancellationRequest |
PartiallyAcceptedTechnicalCorrect |
PaymentCancelled |
PendingCancellationRequest |
Received |
RejectedCancellationRequest |
2.4 4 State Model
2.4.1 Payment 1 Payment Order
The state model for the international-payment resource follows the behaviour and definitions for the ISO 20022 PaymentStatusCode code-set.
...
S.No. | Status | Payment Status Description |
1 | Pending | Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed. |
2 | Rejected | Payment initiation or individual transaction included in the payment initiation has been rejected. |
3 | AcceptedSettlementInProcess | All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution. |
4 | AcceptedSettlementCompleted | Settlement on the debtor's account has been completed. |
5 | AcceptedWithoutPosting | Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account. |
6 | AcceptedCreditSettlementCompleted | Settlement on the creditor's account has been completed. |
3. Data Model
The Data Dictionary section gives the detail on the payload content for the International Payment API flows.
...
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
OBWritePaymentDetailsResponse |
| OBWritePaymentDetailsResponse |
| OBWritePaymentDetailsResponse |
|
|
Data | 1..1 | OBWritePaymentDetailsResponse/Data |
| OBWritePaymentDetailsResponse/Data |
|
|
PaymentStatus | 0..n | OBWritePaymentDetailsResponse/Data/PaymentStatus | Payment status details. | OBWritePaymentDetails |
|
|
4. Usage Examples
4.
...
1 POST /international-payments
4.1.1 Request1 Request
|
|
4.1.2 Response2 Response
|
...