List of APIs for Invalid Payment Method and Failed Reason Response

Invalid payment method token and failed reason response updates.

🚧

NOTE

Ezypay will be invalidating failed payment method tokens.

What this means for newly created invoices?
If an invalid payment method token was used, the create of this invoice will fail. A response indicating that the create invoice cannot use an invalid payment method token will be provided by the create invoice API.

What this means when an invoice is retried?
The API will provide a response to inform the customer that this payment method token cannot be used for the retry.

Improvements to the GET Invoice API

There will be 4 additional items added into the GET Invoice API response body.

  1. paymentMethodInvalid
  2. manualRetryPossible
  3. failedPaymentReason (code, description).
  4. paymentProviderResponse (code, description)

Breakdown on the changes.

The table below provide some explanation to what each of the item means:

Object name

Value

Description

paymentMethodInvalid

true/false

true: Any invoice attempted will not be processed.

false: Any invoice attempted will have their payment attempted.

manualRetryPossible

true/false

false: Any retry using the same payment method token will fail.

true: Any retry using the same payment method token will be successful.

failedPaymentReason (code)

insufficient_funds (example)

Failed Payment Reason will be mapped to an easy to understand what the next cause of action will be.

failedPaymentReason (description)

Payment method has insufficient funds at the time of the transaction (example)

Failed payment response description provide a human readable explanation to why the payment failed.

paymentProviderResponse
subscription (code)

Refused

This is the code that was provided by the payment collector when a payment failed.

paymentProviderResponse
subscription (Description)

51: Insufficient funds/over credit limit / Not sufficient funds (example)

This is the description that was provided by the payment collector when a payment failed.

Invoice (PAID) differences

{
    "id": "6a81ef4d-a218-4706-98fb-e6716fa6abc9",
    "documentNumber": "IN0000000000000488",
    "date": "2019-09-20",
    "dueDate": "2019-09-20",
    "scheduledPaymentDate": null,
    "status": "PAID",
    "memo": null,
    "items": [
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 0.17,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "f2567a6f-2316-4027-b9e5-eccc2c9ec077",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Testing 123",
            "amount": {
                "currency": "AUD",
                "value": 90.00,
                "type": null
            },
            "tax": {
                "rate": 0.00
            },
            "id": "80a52fc1-7a1a-4067-8062-297422344868",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 90.17,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 90.17,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 0.02,
        "type": null
    },
    "customerId": "afe7f91d-3f6d-4830-a53c-5d37aeff1111",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "079967f9-1c31-4a2e-9f82-2e2e194d611c",
    "autoPayment": true,
    "createdOn": "2019-09-20T01:40:44.303",
    "payNowUrl": null
}
{
    "id": "6a81ef4d-a218-4706-98fb-e6716fa6abc9",
    "documentNumber": "IN0000000000000488",
    "date": "2019-09-20",
    "dueDate": "2019-09-20",
    "scheduledPaymentDate": null,
    "status": "PAID",
    "memo": null,
    "items": [
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 0.17,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "f2567a6f-2316-4027-b9e5-eccc2c9ec077",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Testing 123",
            "amount": {
                "currency": "AUD",
                "value": 90.00,
                "type": null
            },
            "tax": {
                "rate": 0.00
            },
            "id": "80a52fc1-7a1a-4067-8062-297422344868",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 90.17,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 90.17,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 0.02,
        "type": null
    },
    "customerId": "afe7f91d-3f6d-4830-a53c-5d37aeff1111",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "079967f9-1c31-4a2e-9f82-2e2e194d611c",
    "autoPayment": true,
    "createdOn": "2019-09-20T01:40:44.303",
    "payNowUrl": null,
    "paymentMethodInvalid": false,
    "manualRetryPossible": true
}

Invoice (PAST_DUE) differences

{
    "id": "9af2b91e-3e76-4be7-1115-e1c9ac5a6fc5",
    "documentNumber": "IN0000000000000457",
    "date": "2019-09-11",
    "dueDate": "2019-09-11",
    "scheduledPaymentDate": null,
    "status": "PAST_DUE",
    "memo": null,
    "items": [
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 1.49,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "128ef6de-9490-4e85-a9b5-591eb5232bef",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Failed Payment Fee",
            "amount": {
                "currency": "AUD",
                "value": 12.00,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "ae65f1e6-c334-4b7b-a44d-8f17ca4cd91e",
            "type": "failed_payment_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 1.49,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "e45e29b4-293e-4e74-96bd-f714922e7512",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Testing",
            "amount": {
                "currency": "AUD",
                "value": 100.00,
                "type": null
            },
            "tax": {
                "rate": 0.00
            },
            "id": "fadede49-0793-4d78-84d0-ed0e6c2cead2",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 114.98,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 114.98,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 1.37,
        "type": null
    },
    "customerId": "edc4ea95-56ba-4e96-a534-3111c8feb5e7",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "e20a2d65-69a1-45b3-99e6-a0539be3d433",
    "autoPayment": false,
    "createdOn": "2019-09-11T07:06:15.885",
    "payNowUrl": ""
}
{
    "id": "9af2b91e-3e76-4be7-1115-e1c9ac5a6fc5",
    "documentNumber": "IN0000000000000457",
    "date": "2019-09-11",
    "dueDate": "2019-09-11",
    "scheduledPaymentDate": null,
    "status": "PAST_DUE",
    "memo": null,
    "items": [
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 1.49,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "128ef6de-9490-4e85-a9b5-591eb5232bef",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Failed Payment Fee",
            "amount": {
                "currency": "AUD",
                "value": 12.00,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "ae65f1e6-c334-4b7b-a44d-8f17ca4cd91e",
            "type": "failed_payment_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 1.49,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "e45e29b4-293e-4e74-96bd-f714922e7512",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Testing",
            "amount": {
                "currency": "AUD",
                "value": 100.00,
                "type": null
            },
            "tax": {
                "rate": 0.00
            },
            "id": "fadede49-0793-4d78-84d0-ed0e6c2cead2",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 114.98,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 114.98,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 1.37,
        "type": null
    },
    "customerId": "edc4ea95-56ba-4e96-a534-3111c8feb5e7",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "e20a2d65-69a1-45b3-99e6-a0539be3d433",
    "autoPayment": false,
    "createdOn": "2019-09-11T07:06:15.885",
    "payNowUrl": "",
    "failedPaymentReason": {
            "code": "insufficient_funds",
        "description": "Payment method has insufficient funds at the time of the transaction."
    },
    "paymentProviderResponse": {
        "code": "Refused",
        "description": "51: Insufficient funds/over credit limit / Not sufficient funds"
    },
    "paymentMethodInvalid": false,
    "manualRetryPossible": true
}
{
    "id": "9af2b91e-3e76-4be7-1115-e1c9ac5a6fc5",
    "documentNumber": "IN0000000000000457",
    "date": "2019-09-11",
    "dueDate": "2019-09-11",
    "scheduledPaymentDate": null,
    "status": "PAST_DUE",
    "memo": null,
    "items": [
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 1.49,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "128ef6de-9490-4e85-a9b5-591eb5232bef",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Failed Payment Fee",
            "amount": {
                "currency": "AUD",
                "value": 12.00,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "ae65f1e6-c334-4b7b-a44d-8f17ca4cd91e",
            "type": "failed_payment_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Transaction Fee",
            "amount": {
                "currency": "AUD",
                "value": 1.49,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "e45e29b4-293e-4e74-96bd-f714922e7512",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Testing",
            "amount": {
                "currency": "AUD",
                "value": 100.00,
                "type": null
            },
            "tax": {
                "rate": 0.00
            },
            "id": "fadede49-0793-4d78-84d0-ed0e6c2cead2",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 114.98,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 114.98,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 1.37,
        "type": null
    },
    "customerId": "edc4ea95-56ba-4e96-a534-3111c8feb5e7",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "e20a2d65-69a1-45b3-99e6-a0539be3d433",
    "autoPayment": false,
    "createdOn": "2019-09-11T07:06:15.885",
    "payNowUrl": "",
    "failedPaymentReason": {
            "code": "invalid_payment_method",
        "description": "Payment method details are invalid. Please use a different payment method"
    },
    "paymentProviderResponse": {
        "code": "Refused",
        "description": "14: Invalid card number"
    },
    "paymentMethodInvalid": true,
    "manualRetryPossible": false
}

📘

Best Practice

Integrators should use the failedPaymentReason code to build any logic around the failed payment handling process in their application. The failedPaymentReason code will be generically mapped regardless of which payment processor Ezypay uses.


Did this page help you?