# Quote Confirmation APIs source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/quote-confirmation-apis/index.md Alert: If you are a Customer contracted with MTS EU or MTS UK, please proceed to [Quotes Confirmation API Specifications for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-quote-confirmation-apis/index.md) and [Quotes Confirmation API Specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-quote-confirmation-apis/index.md) respectively to ensure compliance with the relevant jurisdiction based Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2). ## Quote Confirmation API Suite {#quote-confirmation-api-suite} Enrolling in the Quote Confirmation suite API includes the following APIs: Note: If you would like real time Payment and Quote status updates then enroll in the [Status Change Push Notification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/status-change-api/index.md). ## Environment Domains {#environment-domains} ### Quote Confirmation {#quote-confirmation} * Sandbox/MTF * Production ```Sandbox/MTF https://sandbox.api.mastercard.com/send/partners/{partner-id}/crossborder/quotes/confirmations ``` ```Production https://api.mastercard.com/send/partners/{partner-id}/crossborder/quotes/confirmations ``` ### Cancel Confirmed Quote {#cancel-confirmed-quote} * Sandbox/MTF * Production ```Sandbox/MTF https://sandbox.api.mastercard.com/send/partners/{partner-id}/crossborder/quotes/cancellations ``` ```Production https://api.mastercard.com/send/partners/{partner-id}/crossborder/quotes/cancellations ``` ### Retrieve Confirmed Quote {#retrieve-confirmed-quote} * Sandbox/MTF * Production ```Sandbox/MTF https://sandbox.api.mastercard.com/send/partners/{partner-id}/crossborder/quotes/{transaction-reference}/proposals/{proposal-id} ``` ```Production https://api.mastercard.com/send/partners/{partner-id}/crossborder/quotes/{transaction-reference}/proposals/{proposal-id} ``` Note: **Sandbox** and **MTF** environments share the same url but are differentiated by partner id. ## API {#api} [****Open Specification****](https://static.developer.mastercard.com/content/cross-border-services/swagger/quoteapi_swagger.yaml) Enrolling in the Quote Confirmation Service includes the following APIs: Note: If you would like real time Payment and Quote status updates then enroll in the [Status Change Push](https://developer.mastercard.com/cross-border-services/documentation/api-ref/status-change-api/index.md). ### Quote Confirmation API {#quote-confirmation-api} This API is used to confirm the FX rate quote that you received in the Quotes API. This confirmation is mandatory prior to submitting a payment transaction. The Quote Confirmation needs to be done within the 'confirmationExpiryTime' that is received in the Quotes API response. Getting a successful Quote Confirmation incurs a reserve of funds. If you opt-in 'Late Quote Confirmation policy' and you confirm the quote after `confirmationExpiryTime`, the original quote will be considered as 'Expired' and new quote will be sent in the Quote Confirmation API response. You can now confirm the new quote within the `ConfirmationExpirytime`. The late confirmation will be allowed for maximum of three (3) attempts; afterwards, the confirmation will be declined. API Reference: `GET /send/partners/{partner_id}/crossborder/quotes/confirmations` ### Cancel Confirmed Quote API {#cancel-confirmed-quote-api} This API is used to cancel a confirmed FX rate quote/proposal. If Confirmed Quote cancellation is sent before the payment initiation, the cancellation will result in return of reserved funds. If cancellation is sent after payment initiation, the Confirmed Quote Cancellation will be declined. API Reference: `GET /send/partners/{partner_id}/crossborder/quotes/cancellations` ### Retrieve Confirmed Quote API {#retrieve-confirmed-quote-api} If you opt-in in Quote Confirmation Suite, you can use this API to retrieve quote details requested for payment utilization. API Reference: `GET /send/partners/{partner_id}/crossborder/quotes/{transaction_reference}/proposals/{proposal_id}` ## 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. ### Sandbox Test cases {#sandbox-test-cases} The Sandbox server returns simulated, static responses. You can use the following test cases to produce specific responses. #### Quote Confirmation {#quote-confirmation-1} | Status | Test Case | Action | |---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Confirmed | Quote Confirmation successful response | 1. Send Quote request using 'transactionReference' number starting with '40' 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. | | Pending Ambiguous | Quote Confirmation pending due to technical reason | 1. Send Quote request using 'transactionReference' number starting with '41' 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. | | Pending Expired | Enrolled in late Quote Confirmation policy and submits Quote Confirmation after 'confirmationExpiryTime' receives 'Pending Expired' in the Quote Confirmation API response with new proposal details. | 1. Send Quote using 'transactionReference' number starting with '42' 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 after a min. | | Rejected with 130194 error code | Quote Confirmation response with duplicate Quote Confirmation | 1. Send Quote request using 'transactionReference' number starting with '44' and ending with the 130194 error code. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. For example: Transaction reference '44XXXXXXXX130194' will REJECT quote and return 130194 error code in response | | Rejected with 130195 error code | 'Quote Confirmation is performed after 'confirmationExpiryTime' exceeds | 1. Send Quote request using 'transactionReference' number starting with '44' and ending with the 130195 error code. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. For example: Transaction reference '44XXXXXXXX130195' will REJECT quote and return 130195 error code in response | | Rejected with 130196 error code | Enrolled in pre-funding and does not have sufficient balances in the prefunding account | 1. Send Quote request using 'transactionReference' number starting with '44' and ending with the 130196 error code. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. For example: Transaction reference '44XXXXXXXX130196' will REJECT quote and return 130196 error code in response | | Rejected with 082000 error code | Input validation failure | 1. Send Quote request using 'transactionReference' number starting with '44' and ending with '082000'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. For example: Transaction reference '44XXXXXXXX082000' will REJECT quote and return 082000 error code in response | | Rejected- Can be resubmitted | 150001 System Error: Quote Confirmation can be resubmitted | 1. Send Quote request using 'transactionReference' number starting with '41CR' and ends with '501'. 2. Send a Quote Confirmation using same transaction_reference' number same proposal id from step 1 For example: Transaction reference '41CRXXXXXXXXXX501' will REJECT Quote Confirmation and return 150001 error code in the Quote Confirmation response. 3. Resubmit the initial quote using the same 'transactionReference' after 5 min upto 15 min with same input parameters. Transaction will be processed with status "Success." | #### Cancel Confirmed Quote {#cancel-confirmed-quote-1} | Status | Test Case | Action | |------------------------------|---------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Success | Cancel Confirmed Quote successful response | 1. Send Quote request using 'transactionReference' number starting with '401R' 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Send Quote Cancellation request using the transactionReference and proposalId from step 1 | | Pending Ambiguous | Cancellation Pending for Confirmed Quote due to technical failure | 1. Send Quote request using 'transactionReference' number starting with '402' and ends with '504' or '505' 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Send Quote Cancellation request using the transactionReference and proposalId from step 1 | | Rejected with 130197 error | Received error for cancellation already requested | 1. Send Quote request using 'transactionReference' number starting with '401' and ending with the 130197 error code. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Send Quote Cancellation request using the transactionReference and proposalId from step 1 For example: Transaction reference '401XXXXXXXX130197' will REJECT quote and return 130197 error code in response | | Rejected with 130111 error | Try and cancel Confirmed Quote that was already cancelled | 1. Send Quote request using 'transactionReference' number starting with '401' and ending with the 130111 error code. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Send Quote Cancellation request using the transactionReference and proposalId from step 1 For example: Transaction reference '401XXXXXXXX130111' will REJECT quote and return 130111 error code in response | | Rejected with 082000 error | Input validation failure | 1. Send Quote request using 'transactionReference' number starting with '401' and ending with '082000'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. 3. Send Quote Cancellation request using the transactionReference and proposalId from step 1. For example: Transaction reference '401XXXXXXXX082000' will REJECT quote and return 082000 error code in response. | | Rejected- Can be resubmitted | 150001 System Error: Quote Cancellation is resubmitted successfully | 1. Send Quote request using 'transactionReference' number starting with '402CR' and ends with '501'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Send Quote Cancellation request using the transactionReference and proposalId from step 1 For example: Transaction reference '402CRXXXXXXXXXX501' will REJECT Quote Cancellation and return 150001 error code in the quote response. 4. Resubmit the Quote Cancellation using the same 'transactionReference' and same input parameters after a minute but within 30 minutes after the initial quote call, Transaction will be processed with status "Success." | #### Retrieve Confirmed Quote {#retrieve-confirmed-quote-1} | Status | Test Case | Action | |------------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Record not found | Retrieve Quote - responds with error code - 110507 | Retrieve quote using any 'transactionReference' and proposalId that is not used before. | | Success | Retrieve a Confirmed Quote | 1. Create quote with transactionReference starting with '40'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Retrieve quote with transactionReference and proposalId given in step 2 | | Success | Retrieve Cancelled Confirmed Quote | 1. Create quote with Transaction Reference starting with '401R'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Send Quote Cancellation request using the transactionReference and proposalId from step 2 4. Retrieve Quote with transactionReference and proposalId given in step 2 | | Success | Retrieve a quote where status is pending and stage is expired | 1. Create quote with Transaction Reference starting with '42'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Retrieve quote with transactionReference and proposalId given in step 2 | | Success | Retrieve a quote where status is pending and stage is ambiguous | 1. Create quote with Transaction Reference starting with '41'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1 3. Retrieve quote with transactionReference and proposalId given in step 2 | | Success | Retrieve a Rejected Quote | 1. Create quote with transactionReference starting with '44' and ending with any expected Quote Confirmation error code. For example: Transaction reference '44XXXXXXXX130195'. 2. Send Quote Confirmation request using the transactionReference and proposalId from step 1. 3. Retrieve quote with transactionReference and proposalId given in step 2. | | Success | Retrieve Quote before the Quote Confirmation , Status and stage will be blank. | 1. Create quote with transactionReference starting with '4'. 2. Retrieve quote with transactionReference given in step 1 | ## Quote Confirmation Sample Request {#quote-confirmation-sample-request} * JSON ```JSON { "transactionReference": "41C12344311006563", "proposalId": "pen_4000767745894923464866186" } ``` ## Quote Confirmation Sample Response {#quote-confirmation-sample-response} ### Successful Response {#successful-response} * JSON ```JSON { "transactionReference": "40C12344311006662", "status": "CONFIRMED", "proposalId": "pen_4000837491233982545990059", "paymentSubmissionExpiryTime": "2022-01-28T05:00:35-06:00" } ``` ### Pending Ambiguous Response: {#pending-ambiguous-response} * JSON ```JSON { "transactionReference": "41C12344311006663", "status": "PENDING", "stage": "Ambiguous", "proposalId": "pen_4000353661783596006753363" } ``` ### Pending Expired Response: {#pending-expired-response} * JSON ```JSON { "transactionReference":"42a2421f21e486494799635", "status":"PENDING", "stage":"Expired", "proposalId":"pen_4000033672217723533692871", "proposedQuote":{ "proposals":[ { "id":"pen_4000986534202938713628905", "resourceType":"proposal", "feesIncluded":true, "expirationDate":"2022-01-30T23:44:03-06:00", "quoteFxRate":"777", "chargedAmount":{ "amount":"105.13", "currency":"USD" }, "creditedAmount":{ "amount":"1001.2", "currency":"USD" }, "principalAmount":{ "amount":"100.12", "currency":"USD" }, "confirmationExpiryTime":"2022-01-30T23:44:03-06:00" } ] } } ``` ### Rejected with Specific Error Response: {#rejected-with-specific-error-response} * JSON ```JSON { "Errors":{ "Error":[ { "RequestId":"48883924", "ReasonCode":"DECLINE", "Description":"Confirmation requested for Expired Quote", "Recoverable":false, "Details":{ "Detail":[ { "Name":"ErrorDetailCode", "Value":"130195" } ] } } ] } } ``` ### Rejected - Can be resubmitted Response: {#rejected---can-be-resubmitted-response} * JSON ```JSON { "Errors":{ "Error":[ { "RequestId":"48883968", "Source":"ConfirmQuote", "ReasonCode":"SYSTEM_ERROR", "Description":"A system error has occurred", "Recoverable":false, "Details":{ "Detail":[ { "Name":"ErrorDetailCode", "Value":"150001" } ] } } ] } } ``` ## Quote Cancellation Sample Request {#quote-cancellation-sample-request} * JSON ```JSON { "transactionReference": "41C12344311006563", "proposalId": "pen_4000767745894923464866186" } ``` ## Quote Cancellation Sample Response {#quote-cancellation-sample-response} ### Cancelled Response: {#cancelled-response} * JSON ```JSON { "transactionReference":"401Rb0ebea981f17468d9c4fd", "status":"CANCELLED", "proposalId":"pen_4000555569304844118706334", "releasedReservedAmount":{ "amount":"22.06", "currency":"USD" } } ``` ### Pending Ambiguous Response: {#pending-ambiguous-response-1} * JSON ```JSON { "transactionReference":"402Ff86769988b7e455b90022504", "status":"PENDING", "stage":"Ambiguous", "proposalId":"pen_4000134910763449861927718" } ``` ### Rejected with Specific Error Response: {#rejected-with-specific-error-response-1} * JSON ```JSON { "Errors": { "Error": [ { "RequestId": "186917", "Source": "proposalId", "ReasonCode": "DECLINE ", "Description": "Cancellation not permitted on this transaction", "Recoverable": false, "Details": { "Detail": [ { "Name": "ErrorDetailCode", "Value": "130111" } ] } } ] } } ``` ### Rejected- Can be resubmitted Response: {#rejected--can-be-resubmitted-response} * JSON ```JSON { "Errors":{ "Error":[ { "RequestId":"48883968", "Source":"CancelQuote", "ReasonCode":"SYSTEM_ERROR", "Description":"A system error has occurred", "Recoverable":false, "Details":{ "Detail":[ { "Name":"ErrorDetailCode", "Value":"150001" } ] } } ] } } ``` ## Retrieve Quote sample response {#retrieve-quote-sample-response} ### Retrieve a Confirmed Quote response {#retrieve-a-confirmed-quote-response} * JSON ```JSON { "transactionReference": "40C12344311006762", "resourceType": "quote", "created": "2022-01-31T15:00:31+05:30", "proposalId": "pen_4000195143736799198306423", "confirmStatus": { "status": "CONFIRMED" }, "paymentSubmissionExpiryTime": "2022-01-31T17:00:24+05:30", "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-01-31T15:00:31+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-01-31T15:00:31+05:30" } ] }, "statusTimestamp": "2022-01-31T15:00:31+05:30" } ``` ### Retrieve a Cancelled Quote response {#retrieve-a-cancelled-quote-response} * JSON ```JSON { "transactionReference": "401R12344311006762", "resourceType": "quote", "created": "2022-02-01T08:16:57+05:30", "proposalId": "pen_4000414553565328012680992", "cancelStatus": { "status": "CANCELLED" }, "paymentSubmissionExpiryTime": "2022-02-01T10:15:14+05:30", "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-02-01T08:16:57+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-02-01T08:16:57+05:30" } ] }, "statusTimestamp": "2022-02-01T08:16:57+05:30" } ``` ### Retrieve a pending expired quote response {#retrieve-a-pending-expired-quote-response} * JSON ```JSON { "transactionReference": "42112344311006762", "resourceType": "quote", "created": "2022-02-01T08:40:41+05:30", "proposalId": "pen_4000942245429356229084729", "confirmStatus": { "status": "PENDING", "pendingStage": "Expired" }, "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-02-01T08:40:41+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-02-01T08:40:41+05:30" } ] }, "statusTimestamp": "2022-02-01T08:40:41+05:30" } ``` ### Retrieve a pending ambiguous quote response {#retrieve-a-pending-ambiguous-quote-response} * JSON ```JSON { "transactionReference": "41C12344311006663", "resourceType": "quote", "created": "2022-01-28T14:02:23+05:30", "proposalId": "pen_4000353661783596006753363", "confirmStatus": { "status": "PENDING", "pendingStage": "Ambiguous" }, "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-01-28T14:02:23+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-01-28T14:02:23+05:30" } ] }, "statusTimestamp": "2022-01-28T14:02:23+05:30" } ``` ### Retrieve a Rejected Quote Confirmation {#retrieve-a-rejected-quote-confirmation} * JSON ```JSON { "transactionReference": "44157453474311130195", "resourceType": "quote", "created": "2022-02-01T13:12:55+05:30", "proposalId": "pen_4000903991319632726051612", "confirmStatus": { "status": "REJECTED", "errorCode": "150001", "errorMessage": "A system error has occurred" }, "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-02-01T13:12:55+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-02-01T13:12:55+05:30" } ] }, "statusTimestamp": "2022-02-01T13:12:55+05:30" } ``` ### Retrieve a Rejected Quote cancellation {#retrieve-a-rejected-quote-cancellation} * JSON ```JSON { "transactionReference": "44157453474311130195", "resourceType": "quote", "created": "2022-02-01T13:12:55+05:30", "proposalId": "pen_4000903991319632726051612", "cancelStatus": { "status": "REJECTED", "errorCode": "130111", "errorMessage": "Cancellation not permitted on this transaction" }, "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-02-01T13:12:55+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-02-01T13:12:55+05:30" } ] }, "statusTimestamp": "2022-02-01T13:12:55+05:30" } ``` ### Retrieve quote prior to confirmation response {#retrieve-quote-prior-to-confirmation-response} * JSON ```JSON { "transactionReference": "40C12344311006762", "resourceType": "quote", "created": "2022-01-31T14:57:38+05:30", "proposalId": "pen_4000195143736799198306423", "quote": { "proposals": [ { "resourceType": "proposal", "feesIncluded": true, "expirationDate": "2022-01-31T14:57:38+05:30", "chargedAmount": { "amount": "105.13", "currency": "USD" }, "creditedAmount": { "amount": "1001.2", "currency": "USD" }, "principalAmount": { "amount": "100.12", "currency": "USD" }, "confirmationExpiryTime": "2022-01-31T14:57:38+05:30" } ] } } ``` ### Status and Stage matrix {#status-and-stage-matrix} | Status | Stage | Description | |-----------|-----------|-----------------------------------------------------------------------------------------------| | Confirmed | | Quote is confirmed | | Cancelled | | Quote is cancelled | | Pending | Ambiguous | Technical error | | Pending | Expired | Quote is expired and new quote is sent for customers opting in late Quote Confirmation policy | | Rejected | | Quote request is rejected. Accompanied by error code and error message. | ## 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).