# Testing source: https://developer.mastercard.com/mastercard-send-disbursements/documentation/testing/index.md ## Sandbox Testing {#sandbox-testing} Use this guidance to perform initial Sandbox testing for the Disbursement API. It covers the recommended workflow, positive and negative coverage, and test cases. The Sandbox server returns simulated responses, enabling you to try this API quickly, and should not be used for full integration testing. For valid test card numbers that you can use in your requests, see [Sandbox Test Cards](https://developer.mastercard.com/mastercard-send/documentation/implementation/sandbox-test-cards/). Do not use real consumer card numbers in the Sandbox environment. When you are ready to test your integration, move to MTF, a production-like environment, to validate your integration before Production; see [MTF Testing](https://developer.mastercard.com/mastercard-send-disbursements/documentation/testing/index.md#mtf-testing). ### Choose a testing method {#choose-a-testing-method} Choose a testing method that best matches how you want to validate requests: * **[Postman Collection](https://developer.mastercard.com/mastercard-send-disbursements/documentation/developer-tools/postman-collection/index.md)** --- pre-built requests with OAuth configured. * **[Reference Application](https://developer.mastercard.com/mastercard-send-disbursements/documentation/developer-tools/reference-app/index.md)** --- a working implementation you can run and inspect. * Custom API client generated as per the guidance in [Java API Client](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/api-tutorial/index.md). ### Recommended testing workflow {#recommended-testing-workflow} Use the following sequence to validate the endpoints with a realistic flow: 1. Create a disbursement using the POST API. 2. Retrieve the disbursement details using the GET API with the Disbursement ID. 3. Retrieve the disbursement details using the GET API with the Disbursement Reference. ### Positive testing {#positive-testing} Positive testing confirms that valid requests succeed and return the expected data. Validate these behaviors: * Valid request bodies return success codes such as `201 Created` or `200 OK`. * Created disbursements have the expected response values. * Disbursements can be retrieved by Disbursement Reference or Disbursement ID. For test data and expected responses, see [Test cases](https://developer.mastercard.com/mastercard-send-disbursements/documentation/testing/index.md#test-cases). The example below is a positive test case request body for a `POST /v1/partners/{partnerId}/disbursements/payment` API call. It includes a special `disbursement_reference` value that should give a Sandbox success response. * JSON * XML ```JSON { "payment_disbursement": { "disbursement_reference": "HAPPYPATH_DISB_000001", "payment_type": "BDB", "amount": "5300", "currency": "USD", "sender_account_uri": "pan:5102589999999921;exp=2077-02;cvc=123", "sender": { "first_name": "John", "last_name": "Jones", "account_type": "03", "address": { "line1": "101 Main St", "line2": "Unit 5", "city": "Chicago", "country_subdivision": "IL", "postal_code": "60618", "country": "USA" } }, "recipient_account_uri": "pan:5102589999999913;exp=2077-08;cvc=123", "recipient": { "first_name": "Jane", "last_name": "Smith", "account_type": "03", "address": { "line1": "234 Spiral Drive", "line2": "Unit B", "city": "St. Louis", "country_subdivision": "MO", "postal_code": "63368", "country": "USA" } }, "participant": { "merchant_category_code": "6536" }, "funding_source": "DEBIT", "transaction_purpose": "00" } } ``` ```XML HAPPYPATH_DISB_000001 BDB 5300 USD pan:5102589999999921;exp=2077-02;cvc=123 John Jones 03
101 Main St Unit 5 Chicago IL 60618 USA
pan:5102589999999913;exp=2077-08;cvc=123 Jane Smith 03
234 Spiral Drive Unit B St. Louis MO 63368 USA
6536 DEBIT 00 ``` Expected result: `201 Created` and a response body containing the `disbursement_reference` value used in the API request, a generated `id` value ('HAPPYPATH_DISB_000001_txn' for this request), and a `status` of 'APPROVED'. Additional checks: * `GET /v1/partners/{partnerId}/disbursements` with `ref` header value of 'HAPPYPATH_DISB_000001' returns `200 OK` and the disbursement details. * `GET /v1/partners/{partnerId}/disbursements/HAPPYPATH_DISB_000001_txn` returns `200 OK` and the disbursement details. ### Negative testing {#negative-testing} Negative testing confirms that invalid requests fail cleanly and return useful error details. Validate these behaviors: * Missing required fields return `400 Bad Request`. * Invalid field values return validation errors with a clear `ReasonCode` and `Description`. * GET requests for unknown disbursements return `404 Not Found`. * Incorrect or missing authentication data is rejected. For test data and expected responses, see [Test cases](https://developer.mastercard.com/mastercard-send-disbursements/documentation/testing/index.md#test-cases). For the error response message structure and a complete list of error codes and reason codes, see [Error Codes](https://developer.mastercard.com/mastercard-send-disbursements/documentation/response-error-codes/error-codes/index.md). ### Test cases {#test-cases} Use the following test cases to produce specific responses. As long as the request message is properly formatted, a valid response will be returned. ##### POST - Create Disbursement {#post---create-disbursement} | Test Scenario | Test Data | HTTP Status Code/Reason Code | Expected Result | |-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|------------------------------|-------------------------------------------------------------------------------------------------| | Always disbursement approval | Valid request with `disbursement_reference` value HAPPYPATH_DISB_000001 | 201/CREATED | Approved | | Disbursement approval | Valid request with unique valid `disbursement_reference` value that does not match one of the test scenarios below | 201/CREATED | Approved | | Decline - 402 response | `disbursement_reference` starts with DEC05 | 402/DECLINE | Card declined | | Unknown - 202 response | `disbursement_reference` starts with UNKNWN | 202/ACCEPTED | Status unknown | | Decline - duplicate disbursement reference | In same day, send request with same `disbursement_reference` as a previous request but different `amount` | 409/RESOURCE_ERROR | Error: `disbursement_reference`, duplicate value (110501) | | Country not supported for the partner | `disbursement_reference` starts with PCNS | 402/RESOURCE_ERROR | Error: Country not supported for merchant (110516) | | Sending account not eligible | `disbursement_reference` starts with PINES | 400/RESOURCE_ERROR | Error: `sender_account_uri`, account not eligible (110503) | | Receiving account not eligible | `disbursement_reference` starts with PINER | 400/RESOURCE_ERROR | Error: `recipient_account_uri`, account not eligible (110503) | | Invalid value | `payment_type` = ABC | 400/INVALID_INPUT_VALUE | Error: Invalid value (082000) | | Invalid field length | `disbursement_reference` = 123 | 400/INVALID_INPUT_LENGTH | Error: Invalid length (072000) | | Missing required field | Omit a required parameter, such as `disbursement_reference` | 400/MISSING_REQUIRED_INPUT | Error: Value is required (092000) | | Transaction limit error | `disbursement_reference` starts with TNLMT | 400/DECLINE | Error: `amount`, transaction limit is less than the minimum configured for the partner (130006) | | Partner daily limit exceeded | `disbursement_reference` starts with PDLMTX | 400/DECLINE | Error: `amount`, partner has exceeded the daily limit configured in the system (130005) | | Partner not active | `disbursement_reference` starts with PINA | 401/INVALID_INPUT_VALUE | Error: `partnerId`, invalid value (082000) | | Partner not onboarded | `disbursement_reference` starts with PUNK | 401/INVALID_INPUT_VALUE | Error: `partnerId`, invalid value (072000) | | Client user not associated with partner | `disbursement_reference` starts with PCLNT | 401/AUTHORIZATION_FAILED | Error: `OpenAPIClientId`, unauthorized access (050007) | | Partner's processing is suspended in the system | `disbursement_reference` starts with PSPND | 403/AUTHORIZATION_FAILED | Error: `partnerId`, transaction processing suspended (050005) | | Application system error | `disbursement_reference` starts with SE500 | 500/SYSTEM_ERROR | Error: Internal exception occurred | ##### GET - Retrieve by Disbursement ID {#get---retrieve-by-disbursement-id} | Test Scenario | Test Data | HTTP Status Code/Reason Code | Reason Description | |---------------------------------------------------|---------------------------------------------------------------------------------------------------------|------------------------------|----------------------------------------------------| | Retrieve details of previous disbursement request | `disbursementId` path value matches the `id` returned in a previous successful POST API call to Sandbox | 200/OK | Successful | | Unsuccessful GET call | `disbursementId` path value not used before | 404/RESOURCE_ERROR | Error: `disbursementId`, record not found (110507) | ##### GET - Retrieve by Disbursement Reference {#get---retrieve-by-disbursement-reference} | Test Scenario | Test Data | HTTP Status Code/Reason Code | Reason Description | |---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|------------------------------|------------------------------------------------------------| | Retrieve details of previous disbursement request | `ref` query value matches the `disbursement_reference` value used in a previous successful POST API call to Sandbox | 200/OK | Successful | | Unsuccessful GET call | `ref` query value not used before | 404/RESOURCE_ERROR | Error: `disbursement_reference`, record not found (110507) | ## MTF Testing {#mtf-testing} The Mastercard Customer Implementation Services (CIS) team, assigned during implementation, can provide test cases and assist with testing. For test card numbers that you can use for testing the Disbursement API in the MTF environment, see [MTF Test Cards](https://developer.mastercard.com/mastercard-send/documentation/implementation/test-cards/). Do not use consumer card numbers in the test environment. Transactions in the MTF environment are not executed against other networks. ## Next Steps {#next-steps} * Consult the [API Reference](https://developer.mastercard.com/mastercard-send-disbursements/documentation/api-reference/disbursement/index.md) for complete endpoint specifications, request and response schemas, and environment URLs. * If you run into issues, visit [Support](https://developer.mastercard.com/mastercard-send-disbursements/documentation/support/index.md) for FAQs and troubleshooting guidance.