# Testing
source: https://developer.mastercard.com/payment-initiation-api/documentation/testing/index.md

Use this page to plan and execute Sandbox validation for the Payment Initiation API. It covers the recommended workflow, positive and negative coverage, and the reference guides you need for endpoint-level execution.
Note: Start all validation in Sandbox before moving to Production.

### Choose a testing method {#choose-a-testing-method}

Choose a testing method that best matches how you want to validate requests:

* [Reference Application](https://developer.mastercard.com/payment-initiation-api/documentation/developer-tools/reference-app/index.md) --- pre-built requests with OAuth and encryption configured.
* [Insomnia Collection](https://developer.mastercard.com/payment-initiation-api/documentation/developer-tools/insomnia-collection/index.md) --- an alternative API client with a ready-to-use workspace.
* Custom API client generated as per guidance in [API Basics](https://developer.mastercard.com/payment-initiation-api/documentation/api-basics/index.md).

## Positive testing {#positive-testing}

Positive testing confirms that valid requests succeed and return the expected data.

### Validate these behaviors {#validate-these-behaviors}

* Valid request bodies return success codes such as `200 OK` or `201 Created`.
* Created resources can be retrieved by ID or found through search.
* Updates persist and can be verified with a follow-up GET.
* Encrypted endpoints accept correctly signed and encrypted payloads.

### Positive test cases {#positive-test-cases}

View the representative positive test case for the `POST` endpoint.

#### [Commercial Card Payment Initiation](https://developer.mastercard.com/payment-initiation-api/documentation/use-cases/commercial-card-payment-initiation/index.md) {#commercial-card-payment-initiationhahahugoshortcodes4hbhb}

`POST /debtor-agents/{ica}/payment-initiations`
* Json

```json
{
  "paymentInformation": {
    "paymentInformationIdentification": "ZWSeE2gq2qWIyLP3HYeDaSLoTb9r7zKS",
    "paymentMethod": "CARD",
    "requestedExecutionDate": "2025-02-02",
    "debtor": {
      "name": "Debtor Company",
      "postalAddress": {
        "streetName": "2200 Mastercard Blvd",
        "postalCode": "63368",
        "townName": "O'Fallon",
        "countrySubDivision": "MO",
        "country": "US"
      },
      "identification": {
        "organisationIdentification": {
          "anyBIC": "7OZBBAAX",
          "lei": "81G1IF550C4PM62Z6075",
          "other": [
            {
              "identification": "123456789",
              "schemeName": {
                "code": "TXID"
              },
              "issuer": "Issuer Name"
            }
          ]
        }
      }
    },
    "debtorAccount": {
      "identification": {
        "other": [
          {
            "identification": "1234",
            "schemeName": {
              "code": "AIIN"
            },
            "issuer": "Issuer Name"
          }
        ]
      },
      "type": {
        "code": "CARD"
      },
      "currency": "USD",
      "name": "Debtor Card"
    },
    "creditTransferTransactionInformation": {
      "paymentIdentification": {
        "instructionIdentification": "W4gemK5OLnyEtZbDN6x17ysPn3Ig2WB0",
        "endToEndIdentification": "W4gemK5OLnyEtZbDN6x17ysPn3Ig2WB0",
        "uetr": "019029c1-0ec6-7ebe-996b-5e0e274b766b"
      },
      "amount": {
        "instructedAmount": {
          "currency": "USD",
          "amount": 576.83
        }
      },
      "exchangeRateInformation": {
        "unitCurrency": "USD",
        "exchangeRate": 0.7,
        "rateType": "SPOT",
        "contractIdentification": "qwjhr-otpr-0012"
      },
      "chargeBearer": "DEBT",
      "creditor": {
        "name": "Creditor Name",
        "postalAddress": {
          "streetName": "2200 Townhall Blvd",
          "postalCode": "63368",
          "townName": "O'Fallon",
          "countrySubDivision": "MO",
          "country": "US"
        },
        "identification": {
          "organisationIdentification": {
            "anyBIC": "1N62MG41",
            "lei": "0562S5G0LCO2W269S657",
            "other": [
              {
                "identification": "matest.creditor6@stp",
                "schemeName": {
                  "code": "PRID"
                },
                "issuer": "Issuer Name"
              }
            ]
          }
        }
      },
      "tax": {
        "totalTaxAmount": {
          "currency": "USD",
          "amount": 10
        }
      },
      "relatedRemittanceInformation": [
        {
          "remittanceIdentification": "a61R80u9QmLcduhLQG4uogTTRUQIQi4k",
          "remittanceLocationDetails": [
            {
              "method": "URID",
              "electronicAddress": "https://www.buyer.com/remittancedetails",
              "name": "Creditor Name",
              "postalAddress": {
                "streetName": "2200 Mastercard Blvd",
                "postalCode": "63368",
                "townName": "O'Fallon",
                "countrySubDivision": "MO",
                "country": "US"
              }
            }
          ]
        }
      ],
      "remittanceInformation": {
        "unstructured": [
          "email: testcreditor@hotmail.com",
          "URL: https://exampleinvoice.com/GLCode:200"
        ],
        "structured": [
          {
            "referredDocumentInformation": [
              {
                "type": {
                  "code": "CINV"
                },
                "number": "AB7894565235",
                "relatedDate": [
                  {
                    "type": {
                      "code": "PADD"
                    },
                    "date": "2025-12-24"
                  }
                ],
                "lineDetails": [
                  {
                    "identification": [
                      {
                        "type": {
                          "code": "MDNB",
                          "issuer": "eVCUtkC_cF0tQcp7fbLzbJRass4k"
                        },
                        "number": "Mi18v1ddVoaNIHNOh",
                        "relatedDate": "2025-06-24"
                      }
                    ],
                    "description": "line detail identification code",
                    "amount": {
                      "remittanceAmountandType": [
                        {
                          "type": {
                            "code": "DUPA"
                          },
                          "currency": "USD",
                          "amount": 210.05
                        }
                      ],
                      "adjustmentAmountAndReason": [
                        {
                          "currency": "USD",
                          "amount": 10,
                          "creditDebitIndicator": "CRDT",
                          "reason": "DAMAGED_GOODS",
                          "additionalInformation": "Damaged Goods"
                        }
                      ]
                    }
                  }
                ]
              }
            ],
            "referredDocumentAmount": {
              "remittanceAmountandType": [
                {
                  "type": {
                    "code": "REMI"
                  },
                  "currency": "USD",
                  "amount": 200.05
                }
              ],
              "adjustmentAmountAndReason": [
                {
                  "currency": "USD",
                  "amount": 10,
                  "creditDebitIndicator": "DBIT",
                  "reason": "DAMAGED_GOODS",
                  "additionalInformation": "Damaged Goods"
                }
              ]
            },
            "creditorReferenceInformation": {
              "type": {
                "code": "DISP",
                "issuer": "Issuer Name"
              },
              "reference": "RF18539007547034"
            },
            "invoicer": {
              "name": "Invoicer Name",
              "postalAddress": {
                "streetName": "2200 Mastercard Blvd",
                "postalCode": "63368",
                "townName": "O'Fallon",
                "countrySubDivision": "MO",
                "country": "US"
              },
              "identification": {
                "organisationIdentification": {
                  "anyBIC": "88B0GWVU",
                  "lei": "064QB7W3N1S0AW0QJG94",
                  "other": [
                    {
                      "identification": "pTL80r",
                      "schemeName": {
                        "code": "CUST"
                      },
                      "issuer": "Issuer Name"
                    }
                  ]
                }
              }
            },
            "invoicee": {
              "name": "Invoicee Name",
              "postalAddress": {
                "streetName": "2200 Mastercard Blvd",
                "postalCode": "63368",
                "townName": "O'Fallon",
                "countrySubDivision": "MO",
                "country": "US"
              },
              "identification": {
                "organisationIdentification": {
                  "anyBIC": "88B0GWVU",
                  "lei": "064QB7W3N1S0AW0QJG94",
                  "other": [
                    {
                      "identification": "pTL80r",
                      "schemeName": {
                        "code": "CUST"
                      },
                      "issuer": "Issuer Name"
                    }
                  ]
                }
              }
            },
            "additionalRemittanceInformation": [
              "email: testcreditor@hotmail.com",
              "URL: https://exampleinvoice.com/GLCode:200"
            ]
          }
        ]
      },
      "supplementaryData": {
        "envelope": {
          "cardDetails": {
            "pan": "5149612222222220",
            "expiryDate": "2025-11",
            "cvv": "100",
            "cardholderName": "John Doe",
            "currency": "USD",
            "cardholderAddress": {
              "streetName": "2200 Mastercard Blvd",
              "postalCode": "63368",
              "townName": "O'Fallon",
              "countrySubDivision": "MO",
              "country": "US"
            },
            "additionalCardDetails": {
              "validFrom": "2017-07-21T17:32:28.000Z",
              "validTo": "2017-07-21T17:32:28.000Z"
            }
          },
          "chargesInformation": [
            {
              "currency": "USD",
              "type": {
                "code": "CARD_FEE"
              },
              "amount": 256.78
            }
          ]
        }
      }
    }
  }
}
```

Expected result: `201 Created` and a response body containing a generated `Credit Transfer Initiation Result`.

```json
{
  "instructionIdentification": "0c09de10-7e43-40ed-a751-122cf8c4f0ab",
  "paymentStatus": {
    "status": "ACCEPTED",
    "statusReasonInformation": [
      {
        "description": "This transaction is in transit.",
        "reasonCode": "MIN_INSTRUCTED_AMT_WARNING"
      }
    ]
  },
  "createdDate": "2025-08-14T12:41:21.021Z"
}
```

Additional checks:

* `GET /debtor-agents/{ica}/payment-initiations/{instruction_identification}` returns `200 OK`.
* `PUT /debtor-agents/{ica}/payment-initiations/{instruction_identification}` returns `204 No Content`.

## Negative testing {#negative-testing}

Negative testing confirms that invalid requests fail cleanly and return useful error details.

### Validate these behaviors {#validate-these-behaviors-1}

* Missing required fields return `400 Bad Request`.
* Invalid field values return validation errors with a clear `ReasonCode` and `Description`.
* Requests for unknown resources return `404 Not Found`.
* Incorrect or missing authentication data is rejected.
* Encrypted endpoints reject malformed or unencrypted payloads when encryption is required.

### Negative test cases {#negative-test-cases}

View the representative negative test case for the `POST` endpoint.
* Json

```json
{
  "paymentInformation": {
    "paymentInformationIdentification": "ZWSeE2gq2qWIyLP3HYeDaSLoTb9r7zKS",
    "paymentMethod": "CARD",
    "requestedExecutionDate": "2020-01-01",
    "debtor": {
      "name": "Debtor Company",
      "postalAddress": {
        "streetName": "2200 Mastercard Blvd",
        "postalCode": "63368",
        "townName": "O'Fallon",
        "countrySubDivision": "MO",
        "country": "US"
      },
      "identification": {
        "organisationIdentification": {
          "anyBIC": "7OZBBAAX",
          "lei": "81G1IF550C4PM62Z6075",
          "other": [
            {
              "identification": "123456789",
              "schemeName": {
                "code": "TXID"
              },
              "issuer": "Issuer Name"
            }
          ]
        }
      }
    },
    "debtorAccount": {
      "identification": {
        "other": [
          {
            "identification": "1234",
            "schemeName": {
              "code": "AIIN"
            },
            "issuer": "Issuer Name"
          }
        ]
      },
      "type": {
        "code": "CARD"
      },
      "currency": "USD",
      "name": "Debtor Card"
    },
    "creditTransferTransactionInformation": {
      "paymentIdentification": {
        "instructionIdentification": "W4gemK5OLnyEtZbDN6x17ysPn3Ig2WB0",
        "endToEndIdentification": "W4gemK5OLnyEtZbDN6x17ysPn3Ig2WB0",
        "uetr": "019029c1-0ec6-7ebe-996b-5e0e274b766b"
      },
      "amount": {
        "instructedAmount": {
          "currency": "USD",
          "amount": 576.83
        }
      },
      "exchangeRateInformation": {
        "unitCurrency": "USD",
        "exchangeRate": 0.7,
        "rateType": "SPOT",
        "contractIdentification": "qwjhr-otpr-0012"
      },
      "chargeBearer": "DEBT",
      "creditor": {
        "name": "Creditor Name",
        "postalAddress": {
          "streetName": "2200 Townhall Blvd",
          "postalCode": "63368",
          "townName": "O'Fallon",
          "countrySubDivision": "MO",
          "country": "US"
        },
        "identification": {
          "organisationIdentification": {
            "anyBIC": "1N62MG41",
            "lei": "0562S5G0LCO2W269S657",
            "other": [
              {
                "identification": "matest.creditor6@stp",
                "schemeName": {
                  "code": "PRID"
                },
                "issuer": "Issuer Name"
              }
            ]
          }
        }
      },
      "tax": {
        "totalTaxAmount": {
          "currency": "USD",
          "amount": 10
        }
      },
      "relatedRemittanceInformation": [
        {
          "remittanceIdentification": "a61R80u9QmLcduhLQG4uogTTRUQIQi4k",
          "remittanceLocationDetails": [
            {
              "method": "URID",
              "electronicAddress": "https://www.buyer.com/remittancedetails",
              "name": "Creditor Name",
              "postalAddress": {
                "streetName": "2200 Mastercard Blvd",
                "postalCode": "63368",
                "townName": "O'Fallon",
                "countrySubDivision": "MO",
                "country": "US"
              }
            }
          ]
        }
      ],
      "remittanceInformation": {
        "unstructured": [
          "email: testcreditor@hotmail.com",
          "URL: https://exampleinvoice.com/GLCode:200"
        ],
        "structured": [
          {
            "referredDocumentInformation": [
              {
                "type": {
                  "code": "CINV"
                },
                "number": "AB7894565235",
                "relatedDate": [
                  {
                    "type": {
                      "code": "PADD"
                    },
                    "date": "2025-12-24"
                  }
                ],
                "lineDetails": [
                  {
                    "identification": [
                      {
                        "type": {
                          "code": "MDNB",
                          "issuer": "eVCUtkC_cF0tQcp7fbLzbJRass4k"
                        },
                        "number": "Mi18v1ddVoaNIHNOh",
                        "relatedDate": "2025-06-24"
                      }
                    ],
                    "description": "line detail identification code",
                    "amount": {
                      "remittanceAmountandType": [
                        {
                          "type": {
                            "code": "DUPA"
                          },
                          "currency": "USD",
                          "amount": 210.05
                        }
                      ],
                      "adjustmentAmountAndReason": [
                        {
                          "currency": "USD",
                          "amount": 10,
                          "creditDebitIndicator": "CRDT",
                          "reason": "DAMAGED_GOODS",
                          "additionalInformation": "Damaged Goods"
                        }
                      ]
                    }
                  }
                ]
              }
            ],
            "referredDocumentAmount": {
              "remittanceAmountandType": [
                {
                  "type": {
                    "code": "REMI"
                  },
                  "currency": "USD",
                  "amount": 200.05
                }
              ],
              "adjustmentAmountAndReason": [
                {
                  "currency": "USD",
                  "amount": 10,
                  "creditDebitIndicator": "DBIT",
                  "reason": "DAMAGED_GOODS",
                  "additionalInformation": "Damaged Goods"
                }
              ]
            },
            "creditorReferenceInformation": {
              "type": {
                "code": "DISP",
                "issuer": "Issuer Name"
              },
              "reference": "RF18539007547034"
            },
            "invoicer": {
              "name": "Invoicer Name",
              "postalAddress": {
                "streetName": "2200 Mastercard Blvd",
                "postalCode": "63368",
                "townName": "O'Fallon",
                "countrySubDivision": "MO",
                "country": "US"
              },
              "identification": {
                "organisationIdentification": {
                  "anyBIC": "88B0GWVU",
                  "lei": "064QB7W3N1S0AW0QJG94",
                  "other": [
                    {
                      "identification": "pTL80r",
                      "schemeName": {
                        "code": "CUST"
                      },
                      "issuer": "Issuer Name"
                    }
                  ]
                }
              }
            },
            "invoicee": {
              "name": "Invoicee Name",
              "postalAddress": {
                "streetName": "2200 Mastercard Blvd",
                "postalCode": "63368",
                "townName": "O'Fallon",
                "countrySubDivision": "MO",
                "country": "US"
              },
              "identification": {
                "organisationIdentification": {
                  "anyBIC": "88B0GWVU",
                  "lei": "064QB7W3N1S0AW0QJG94",
                  "other": [
                    {
                      "identification": "pTL80r",
                      "schemeName": {
                        "code": "CUST"
                      },
                      "issuer": "Issuer Name"
                    }
                  ]
                }
              }
            },
            "additionalRemittanceInformation": [
              "email: testcreditor@hotmail.com",
              "URL: https://exampleinvoice.com/GLCode:200"
            ]
          }
        ]
      },
      "supplementaryData": {
        "envelope": {
          "cardDetails": {
            "pan": "5149612222222220",
            "expiryDate": "2025-11",
            "cvv": "100",
            "cardholderName": "John Doe",
            "currency": "USD",
            "cardholderAddress": {
              "streetName": "2200 Mastercard Blvd",
              "postalCode": "63368",
              "townName": "O'Fallon",
              "countrySubDivision": "MO",
              "country": "US"
            },
            "additionalCardDetails": {
              "validFrom": "2017-07-21T17:32:28.000Z",
              "validTo": "2017-07-21T17:32:28.000Z"
            }
          },
          "chargesInformation": [
            {
              "currency": "USD",
              "type": {
                "code": "CARD_FEE"
              },
              "amount": 256.78
            }
          ]
        }
      }
    }
  }
}
```

### Example error response {#example-error-response}

The OpenAPI spec defines error examples in the following structure:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "Commercial Direct Payments",
        "ReasonCode": "REQUESTED_EXECUTION_DATE_OUT_OF_RANGE",
        "Description": "Enter a valid request execution date. Requested execution date must not be in the past.",
        "Recoverable": false,
        "Details": "correlationid: 0.196f2717.1777472693.7eaba388"
      }
    ]
  }
}
```

Expected result: `400 Bad Request` because `requestedExecutionDate` for the payment transaction is in the past.

Additional checks:

* `GET /debtor-agents/{ica}/payment-initiations/{instruction_identification}` returns `404 Not found`.
* `PUT /debtor-agents/{ica}/payment-initiations/{instruction_identification}` returns `404 Bad request`.  

For the complete list of response codes, reason codes, and formatting rules, see [Codes and Formats](https://developer.mastercard.com/payment-initiation-api/documentation/code-and-formats/index.md).

### Next steps {#next-steps}

* Consult the [API Reference](https://developer.mastercard.com/payment-initiation-api/documentation/api-reference/index.md) for complete endpoint specifications, request and response schemas, and environment URLs.
* If you run into issues, visit [Support](https://developer.mastercard.com/payment-initiation-api/documentation/support/index.md) for FAQs and troubleshooting guidance.