Dishonour Codes

When a payment attempt fails, you will receive a dishonour code that maps to one of the following. These are in order of how common they occur.

Recommended handling per code

insufficient-funds

The most common failure. The payer's account did not have enough funds when Pinch attempted to debit.

Recommended action:

1. Wait at least 24 hours before retrying (next business day is ideal, to allow the payer's salary or other funds to clear).
2. Notify the payer via email or SMS that the payment failed and ask them to ensure sufficient funds.
3. Retry the same payment using the Save Payment endpoint with a new transactionDate.
4. After 3 consecutive failures, consider pausing automatic collection and contacting the payer directly.

temporary-problem

A transient bank refusal, often caused by velocity limits, unusual activity patterns, or the payment being attempted too soon after another.

Recommended action:

1. Wait at least 1 hour, or preferably until the next business day.
2. Retry without contacting the payer first; many temporary-problem dishonours resolve on a simple retry.
3. If retrying still fails with temporary-problem after 2 attempts, notify the payer and ask them to check with their bank.

blocked-by-bank

The bank has permanently blocked the transaction. This is typically triggered by fraud detection, a frozen account, a cancelled card, or a customer initiating a dispute.

Recommended action:

1. Do not retry: further attempts will fail and may trigger additional fraud flags.
2. Immediately notify the payer that their payment method has been declined by their bank.
3. Ask the payer to provide a different payment method (create a new source).
4. Consider suspending the payer's access to your service until a valid payment method is provided.

invalid-card

The card number, expiry date, or CVC is incorrect, or the card has expired.

Recommended action:

1. Do not retry with the same card details.
2. Contact the payer and ask them to re-enter their card details using your tokenisation form.
3. Create a new payment source with the updated token and reschedule the payment.

invalid-account

The bank account BSB or account number is invalid or no longer exists.

Recommended action:

1. Do not retry with the same account details.
2. Contact the payer and ask them to provide their current bank account details.
3. Tokenise the new bank account via CaptureJS and create a new payment source.
4. Reschedule the payment against the new source.

unsupported-card

The card scheme (e.g. Diners Club, UnionPay) is not supported.

Recommended action:

1. Do not retry.
2. Inform the payer that their card type is not supported.
3. Ask the payer to use a Visa or Mastercard instead.

technical-error

An unexpected error on Pinch's infrastructure. These are rare.

Recommended action:

1. Retry once after a short delay (30 minutes).
2. If the retry also fails, contact [email protected] with the payment ID so Pinch can investigate.
3. Do not retry more than once without contacting support.

Dishonour events

When a payment is dishonoured you will receive a bank-results event containing the failed payments and their dishonour codes. See the Events Guide for the full payload format.

For bank account payments, dishonours arrive in the bank-results event after the overnight processing run. For credit card realtime payments, the failure is returned synchronously in the API response.

Testing with the Sandbox API

To test any of these dishonour types within the sandbox API, you are able to add the dishonour code anywhere into a payment description or a Payer first name prefixed by a # for example #invalid-card will result in an invalid-card dishonour code.

var result = await api.Payment.ExecuteRealtime(new RealtimePaymentSaveOptions()
{
    FullName = "Ben Hotdog",
    Email = "[email protected]",
    CreditCardToken = "tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXX",
    Amount = 1245,                
    Description = "this transaction will fail with #insufficient-funds"
});

curl https://api.getpinch.com.au/test/payments/realtime \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Ben Hotdog",
    "email": "[email protected]",
    "amount": 1245,
    "description": "this transaction will fail with #insufficient-funds",
    "creditCardToken": "tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }'