Error reasons

When a payment isn't successful, the API still responds with HTTP status 200 OK or 201 Created, but the transaction status is error. The transaction tells you why in two fields:

• outcomes: the structured result of each stage of the payment, such as the status and response code of the authorisation. Base your logic on these.
• reason: a short text that explains why the payment was refused. Show it in your logs or to your support team.

{
  "status": "error",
  "transactions": [
    {
      "status": "error",
      "payment_method": "credit-card",
      "reason": "Do not honor",
      "outcomes": {
        "processing": {
          "status": "declined",
          "response_code": "05",
          "response_code_description": "Do not honor"
        }
      }
    }
  ]
}

OutcomesCopy Anchor Link

outcomes holds an object for each stage the payment went through. A stage that didn't run, or doesn't apply, isn't in it.

Fraud preventionCopy Anchor Link

outcomes.fraud_prevention is the result of the fraud check of the payment.

{
  "outcomes": {
    "fraud_prevention": {
      "status": "declined",
      "score": "50.0",
      "reason": "Same BIN used repeatedly with the same merchant"
    }
  }
}

ProcessingCopy Anchor Link

outcomes.processing is the result of the authorisation with the card scheme and the card issuer.

If the merchant_advice_code field is populated it is advised to follow the advise from the scheme. The most common ones:

See the documentation of Mastercard for all codes.

Decline reasonsCopy Anchor Link

When the issuer or card scheme declines a payment, outcomes.processing.response_code_description is one of the texts below. The transaction reason holds the same text.

The Source column shows who refused the payment:

• Issuer: the card issuer (your customer's bank). Your customer can usually solve it with their bank, or by using another card or payment method.
• Card scheme: the card scheme network, such as Visa or Mastercard, for example because the payment couldn't be routed.

Platform errorsCopy Anchor Link

When Ginger Payments or the integration refuses the payment before it reaches the card network, for example because of invalid data in your request, there's no response_code_description. The transaction reason is one of these texts:

Response codesCopy Anchor Link

The response code of the card network is in outcomes.processing.response_code, and also in payment_method_details.authorization_iso_response_code. For its meaning, see the documentation of the card scheme.

3-D Secure error reasonsCopy Anchor Link

When 3-D Secure authentication fails, the reason is one of these, followed by a transStatusReason code:

The transStatusReason code tells you why:

See 3D Secure for how authentication works.