Integration Guides
EZYPAYHOW EZYPAY WORKSPARTNERS

On Demand

Suggest Edits

On-demand invoicing allows integrators to bill customers only when they send an invoice request. With the 'on-demand' model, Ezypay does not maintain billing schedules for recurring payments; instead, integrators handle these schedules and send the request as required.

This model allows integrators to collect one-time payments and recurring payments with the same method.

Pre-requisites

Customer creation

Before billing, ensure the customer is created in Ezypay and the unique customer ID is available. Please refer to Customer Creation for more details.

Payment method collected

Ensure at least one payment method is collected and linked to the customer. Please refer to Payment Method Collection for more details.

Get started

Use Create Invoice API to create invoices. Payments are processed immediately upon invoice creation unless schedulePaymentDate is specified.

  1. Provide the customerId and invoice item in the items object.
  2. Retrieve the id of the created invoice for tracking in your platform.
{
  "customerId": "5e123ba5-ef8c-12c4-8fd3-5a1234a6a12f",
  "items": [
    {
      "amount": {
        "currency": "AUD",
        "value": 33.25
      },
      "description": "One week membership"
    }
  ]
}

{
    "id": "cb1d6893-65ae-474c-844b-92ff47ec0c04",
    "creditNoteId": null,
    "documentNumber": "IN0000000000004192",
    "date": "2024-11-20",
    "dueDate": "2024-11-20",
    "scheduledPaymentDate": null,
    "status": "PROCESSING",
    "memo": null,
    "items": [
        {
            "description": "One week membership",
            "amount": {
                "currency": "AUD",
                "value": 33.25,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "a2cf5ccd-e98b-428a-a307-a579debcb2ec",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
        },
        {
            "description": "Standard Visa/Master Fee",
            "amount": {
                "currency": "AUD",
                "value": 2.60,
                "type": null
            },
            "tax": {
                "rate": 10.00
            },
            "id": "881de0bc-b6ca-4a8c-93a3-fbe2fbb1e2ff",
            "type": "transaction_fee",
            "discounted": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            }
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 35.85,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 82.60,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 2.60,
        "type": null
    },
    "customerId": "5e123ba5-ef8c-12c4-8fd3-5a1234a6a12f",
    "subscriptionId": null,
    "checkoutId": null,
    "subscriptionName": null,
    "paymentMethodToken": "5dedc30b-a086-4f8c-9d6d-e0a1dadbbd8f",
    "paymentMethodData": null,
    "autoPayment": true,
    "processingModel": "CARD_ON_FILE",
    "transactionSource": null,
    "createdOn": "2024-11-20T06:42:29.979",
    "payNowUrl": null,
    "channel": "api",
    "checkoutResult": null
}
  1. Set up a webhook to receive outcome for invoices generated.
    1. invoice_paid - Payment success.
    2. invoice_past_due Payment failed.

Best practice

Include fields below during invoice creation

ParameterExplanationMandatory
customerIdEzypay's customer ID in UUID format. Yes
paymentMethodTokenSpecifies the payment method token for billing. Defaults to the primary payment method if not provided.No
itemsArray of objects representing items to bill.Yes
items.amountAmount object, including currency and valueYes
items.descriptionDescription of each item billed.Yes
items.accountingCodeUsed to group similar items in the report.No
externalInvoiceIdUsed to specify the invoice ID from integrators' platform. Requires unique value to achieves idempotency.No
processingModelSupport 2 values:
cardonfile - Use this for one-off purchases.
recurring - Default value. Use this for recurring payment.		No

Use multiple line items

Break down invoices with multiple items into individual items in the request to ensure accurate records in both Ezypay and your platform.

🚧

Attention

For bulk invoice creation, please take into consideration that time to live (TTL) of the token is 60 minutes and you will need to replace it once expired.

Updated 2 months ago