# Retrieve Request API source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/retrieve-request-api/index.md Alert: If you are a Customer contracted with MTS EU or MTS UK, please proceed to [Retrieve Request API Specifications for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/psd2-eu-retrieve-request-api/index.md) and [Retrieve Request API Specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/psd2-uk-retrieve-request-api/index.md) respectively to ensure compliance with the relevant jurisdiction based on Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2). ## Environment Domains {#environment-domains} * Sandbox/MTF * Production ```Sandbox/MTF https://sandbox.api.mastercard.com/send/partners/{partner_id}/crossborder/rfi/requests/{request_id} ``` ```Production https://api.mastercard.com/send/partners/{partner_id}/crossborder/rfi/requests/{request_id} ``` ## API {#api} [**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/RFI+Spec.yaml) This API will be used to retrieve the latest information of a RFI request. The response provides the latest status of the request, information requested of the Customer, response provided by the Customer (when available) and the review status for each field (when available). API Reference: `GET /send/partners/{partner_id}/crossborder/rfi/requests/{request_id}` * **Formats supported** : JSON * **HTTP Version**: 1.0/ 1.1 * **Required HTTP header parameters** : content-type : Format of the inbound content being submitted. example: application/ json content-length: Length of the inbound content body in octets. Accept: Format of the expected response must be provided in this header field. Example- application/json ## API Convention {#api-convention} Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines. ## Payload Encryption {#payload-encryption} All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by Mastercard. For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md) ## Sandbox Testing {#sandbox-testing} You can make API calls to the Sandbox server from your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required OAuth 1.0a Authorization Header. Tip: During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production). This partner ID will not be able to access the sandbox environment, but the customer can still access sandbox by using the non-registered partner ID. Any correctly formatted partner ID can be used in the sandbox. As a best practice, use the first 15 digits of your institution's name (alphanumeric and/or special characters, no spaces) as the Partner_ID. For testing in sandbox, please use unique transaction_reference on each run. Note: The sandbox does not return parameters unique to a specific Customer; such as pricing, limits, and corridor-specific data requirements, but allows you to test general call structure and responses outside of the production environment. After sandbox testing is completed, Customers meeting the eligibility requirements will be assigned a project manager to do integrated testing in the test environment that has been configured to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the Customer. ### Test cases {#test-cases} | Request Status | Test Case | Action | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OPEN | Retrieve a request with status Open created for single payment | 1. Trigger Retrieve Request with request-id starting with "11". For example - "11XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "OPEN" for RFI. | | OPEN | Retrieve a request with status Open created for multiple (3) payments | 1. Trigger Retrieve Request with request-id starting with "22". For example - "22XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "OPEN" for RFI. | | OPEN | Retrieve a request with status Open and request creator has attached a document to the request | 1. Trigger Retrieve Request with request-id starting with "33". For example - "33XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "OPEN" for RFI, along with documentId for the document attached. 3. Trigger Download Document with the documentId (from Step2) to retrieve the document. | | OPEN | Retrieve a request with status Open -\> with additional data requested for Sender | 1. Trigger Retrieve Request with request-id starting with "44". For example - "44XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "OPEN" for RFI. | | OPEN | Retrieve a request with status Open -\> with additional document(s) requested for Recipient | 1. Trigger Retrieve Request with request-id starting with "55". For example - "55XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "OPEN" for RFI. | | Review | Retrieve a request with status Review with comments | 1. Trigger Retrieve Request with request-id starting with "66". For example - "66XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "REVIEW" for RFI. | | INPRORESS | Retrieve a request with status INPROGRESS, where part of the response is accepted. Requesting modification for Sender's Government-Id and all other responses are approved. | 1. Trigger Retrieve Request with request-id starting with "77". For example - "77XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 2. System will return status of "INPROGRESS" for RFI where status for Sender's Government ID Number will be rejected. | ## Sample Requests {#sample-requests} No Request Body ## Sample Responses {#sample-responses} ### 1. Requeststatus Open, created for multiple payment transactions. {#1-requeststatus-open-created-for-multiple-payment-transactions} * JSON ```JSON { "retrieveResponse": { "assignee": "BEL_MASEND5ged2", "creator": "Mastercard", "lastUpdatedDate": "2021-10-25T11:05:00.000+00:00", "other": { "requestDocuments": { "response": { "value": [] } }, "responseDocuments": { "response": { "value": { "request": { "label": "Additional attachments", "kind": "multi_file" }, "response": { "value": [] } } } } }, "requestCreateDate": "2021-10-25T11:05:00.000+00:00", "requestId": "20ef5aef-0598-4741-9945-c0bafc7b5a98", "requestInstruction": "Please provide the information requested.", "requestStatus": "OPEN", "responseType": "NoResponse", "sender": { "fullName": { "request": { "label": "Full name", "kind": "text" }, "response": { "value": "" } } }, "transactions": [ { "paymentDateTime": "2021-10-18T11:05:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "Trans199034810154901" }, { "paymentDateTime": "2021-10-20T11:05:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "Trans2999034810154901" }, { "paymentDateTime": "2021-10-15T11:05:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "Trans3999034810154901" } ] }, "requestStatus": { "requestHistory": [ { "eventActor": "Mastercard", "eventRef": "20da8559-ff57-48ec-855a-be159dcdde45", "eventType": "REQUEST_CREATED", "timestamp": "2021-10-25T11:05:00.000+00:00" } ] } } ``` ### 2. Requeststatus Open, where multiple documents are attached by RFI team. {#2-requeststatus-open-where-multiple-documents-are-attached-by-rfi-team} * JSON ```JSON { "retrieveResponse": { "assignee": "BEL_MASEND5ged2", "creator": "Mastercard", "lastUpdatedDate": "2021-10-25T18:33:01.331732549Z", "other": { "requestDocuments": { "response": { "value": [ "c08a3ea5-9c1f-4b22-96ae-db1446004136", "30a8fbb8-ef0f-4dfb-ac0b-5d4327795c34", "d0204872-6890-46b7-ae6a-70a2168a50f8" ] } }, "responseDocuments": { "response": { "value": { "request": { "label": "Additional attachments", "kind": "multi_file" }, "response": { "value": [] } } } } }, "requestCreateDate": "2021-10-25T18:33:01.331732549Z", "requestId": "30240814-582c-4a96-86d1-72db20d9afb0", "requestInstruction": "Please provide the information requested.", "requestStatus": "OPEN", "responseType": "NoResponse", "sender": { "fullName": { "request": { "label": "Full name", "kind": "text" }, "response": { "value": "" } } }, "transactions": [ { "paymentDateTime": "2021-10-25T12:00:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "0999999034810154901" } ] }, "requestStatus": { "requestHistory": [ { "eventActor": "Mastercard", "eventRef": "70b30d2b-4c42-4904-b596-c00e193169dc", "eventType": "REQUEST_CREATED", "timestamp": "2021-10-25T13:33:01.351385506-05:00" } ] } } ``` ### 3. Requeststatus Open, consisting of additional questions. {#3-requeststatus-open-consisting-of-additional-questions} * JSON ```JSON { "retrieveResponse": { "assignee": "BEL_MASEND5ged2", "creator": "Mastercard", "lastUpdatedDate": "2021-10-25T22:29:42.149617073Z", "other": { "requestDocuments": { "response": { "value": [] } }, "responseDocuments": { "response": { "value": { "request": { "label": "Additional attachments", "kind": "multi_file" }, "response": { "value": [] } } } } }, "paymentAndDocs": { "additionalQuestion": { "request": { "label": "Explain in detail why there are three separate payments to beneficiary on same day", "kind": "text" }, "response": { "value": "" } } }, "recipient": { "additionalQuestion": { "request": { "label": "Passport details", "kind": "text" }, "response": { "value": "" } } }, "requestCreateDate": "2021-10-25T22:29:42.149617073Z", "requestId": "20d5fc18-f506-4cff-a28e-2d3ad5667e70", "requestInstruction": "Please provide the information requested.", "requestStatus": "OPEN", "responseType": "NoResponse", "sender": { "additionalQuestion": { "request": { "label": "Sender's occupation", "kind": "text" }, "response": { "value": "" } } }, "transactions": [ { "paymentDateTime": "2021-10-18T12:00:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "0999999034810154901" }, { "paymentDateTime": "2021-10-18T12:00:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "ABC9999034810154901" }, { "paymentDateTime": "2021-10-18T12:00:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "DEF9999034810154901" } ] }, "requestStatus": { "requestHistory": [ { "eventActor": "Mastercard", "eventRef": "20e73791-3e23-4d40-b66f-8898c1fade10", "eventType": "REQUEST_CREATED", "timestamp": "2021-10-25T17:29:42.176966855-05:00" } ] } } ``` ### 4. Requeststatus Open, requesting additional documents. {#4-requeststatus-open-requesting-additional-documents} * JSON ```JSON { "retrieveResponse": { "assignee": "Mastercard O and T BizOps", "creator": "Mastercard", "lastUpdatedDate": "2021-10-28T19:23:19.095090761Z", "other": { "requestDocuments": { "response": { "value": [] } }, "responseDocuments": { "response": { "value": { "request": { "label": "Additional attachments", "kind": "multi_file" }, "response": { "value": [] } } } } }, "paymentAndDocs": { "additionalDocuments": { "request": { "label": "If sender's source of funds is his/her SALARY, kindly provide 3 consecutive pay stubs", "kind": "multi_file" }, "response": { "value": [] } }, "supportingDocs": { "request": { "label": "Copy of supporting documentation for business payments (e.g. invoice, collaboration agreements, etc.)", "kind": "multi_file" }, "response": { "value": [] } } }, "recipient": { "additionalDocuments": { "request": { "label": "Addition proof of Identity such as a passport, an ID card, a driver license", "kind": "multi_file" }, "response": { "value": [] } } }, "requestCreateDate": "2021-10-28T19:23:19.095090761Z", "requestId": "00de63a7-b99a-4e53-940f-b1c2cd08f292", "requestInstruction": "Please provide the information requested.", "requestStatus": "OPEN", "responseType": "NoResponse", "sender": { "additionalDocuments": { "request": { "label": "Proof of residence such as a utility bill or account statement", "kind": "multi_file" }, "response": { "value": [] } }, "fullAddress": { "documents": { "request": { "label": "Proof of address", "kind": "multi_file" }, "response": { "value": [] } }, "request": { "label": "Full address", "kind": "address" } }, "governmentId": { "documents": { "request": { "label": "Copy of ID", "kind": "multi_file" }, "response": { "value": [] } } } }, "transactions": [ { "paymentDateTime": "2021-10-28T12:00:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "0999999034810154901" } ] }, "requestStatus": { "requestHistory": [ { "eventActor": "Mastercard", "eventRef": "d0171607-6b40-4d35-a021-78a8bcd93524", "eventType": "REQUEST_CREATED", "timestamp": "2021-10-28T14:23:19.113474483-05:00" } ] } } ``` ### 5. Retrieve Request when amendments are requested with mix of approved and rejected responses. {#5-retrieve-request-when-amendments-are-requested-with-mix-of-approved-and-rejected-responses} * JSON ```JSON { "retrieveResponse": { "assignee": "BEL_MASEND5ged2", "creator": "Mastercard", "firstResponseDate": "2021-10-25T11:10:00.000+00:00", "lastUpdatedDate": "2021-10-25T11:55:00.000+00:00", "other": { "comments": [ { "creator": "Mastercard", "text": "Please upload pictures with maximum resolution", "timestamp": "2021-06-15T04:07:00-05:00" } ], "requestDocuments": { "response": { "value": [] } }, "responseDocuments": { "response": { "value": { "review": { "status": "Approved" }, "request": { "label": "Additional attachments", "kind": "multi_file" }, "response": { "value": [] } } } } }, "requestCreateDate": "2021-10-25T11:05:00.000+00:00", "requestId": "20ef5aef-0598-4741-9945-c0bafc7b5a98", "requestInstruction": "Please provide the information requested.", "requestStatus": "INPROGRESS", "responseType": "PartialResponse", "sender": { "fullName": { "review": { "status": "Approved" }, "request": { "label": "Full name", "kind": "text" }, "response": { "value": "John Doe" } }, "governmentId": { "type": { "request": { "label": "Share details", "kind": "string" }, "review": { "status": "Approved" }, "response": { "value": "Answer" } }, "documents": { "request": { "label": "Copy of Id", "kind": "string" }, "review": { "status": "Rejected" }, "response": { "value": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "transactions": [ { "paymentDateTime": "2021-10-18T11:05:00.000+00:00", "recipientUri": "", "senderUri": "", "transactionReference": "0999999034810154901" } ] }, "requestStatus": { "requestHistory": [ { "eventActor": "Mastercard", "eventRef": "f01e0d8c-a591-474c-abf4-3daff165c845", "eventType": "CHANGES_REQUESTED", "timestamp": "2021-10-25T11:55:00.000+00:00" }, { "eventActor": "BEL_MASEND5ged2", "eventRef": "f05bd8a9-9361-486a-a499-ba7fc2802753", "eventType": "RESPONSE_SUBMITTED", "timestamp": "2021-10-25T11:10:00.000+00:00" }, { "eventActor": "Mastercard", "eventRef": "20da8559-ff57-48ec-855a-be159dcdde45", "eventType": "REQUEST_CREATED", "timestamp": "2021-10-25T11:05:00.000+00:00" } ] } } ``` ## Error Codes {#error-codes} Please refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md). For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md). ### Timeout {#timeout} Please allow at least 40 seconds to receive a response from the RFI APIs before considering the request to have timed out, at which point you may retry the call. If consistent timeouts occur, please contact the Cross Border Services Customer Support team at **[crossborder.services.support@mastercard.com](mailto:crossborder.services.support@mastercard.com)**.