List of APIs for Invalid Payment Method and Failed Reason Response

🚧
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.

paymentMethodInvalid
manualRetryPossible
failedPaymentReason (code, description).
paymentProviderResponse (code, description)

Breakdown on the changes.

The table below provides explanations 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.

List of APIs for Invalid Payment Method and Failed Reason Response

🚧
NOTE

Improvements to the GET Invoice API

Breakdown on the changes.

📘
Best Practice

🚧NOTE

Improvements to the GET Invoice API

Breakdown on the changes.

📘Best Practice

🚧
NOTE

📘
Best Practice