Integration Guides
EZYPAYHOW EZYPAY WORKSPARTNERS

Create Partner Invoice

Partner Invoicing can be used to move funds between merchants accounts and wallets. (Eg: This can be used to distribute funds from a franchise merchant to the master franchisee)

Suggest Edits

📘

Before starting with partner Invoices please contact Ezypay at [email protected] to have the accounts configured to use partner invoices

Process Flow on How Partner Invoice Works

Partner Invoice is used when funds collected by Ezypay (from billing) are distributed from one merchant's account to another merchant's account. In order for this to happen, all parties will need to have accounts set up on Ezypay. The receiving merchant does not need to be using Ezypay's billing services to have funds settled into their account. Below is a process flow displaying how partner invoice works.

Alt text

As an example, Partner Invoices can be useful if your business model operates as franchise, you can arrange to have your franchisee's pay their franchise fees, royalty fees, equipment hire fees, etc as a partner invoice rather than having to manage this separately. In simpler terms, it's Ezypay helping you manage your payments.

📘

Scenario

Franchisee Gym A needs to pay head office/franchisor $1000 franchise fees each month.

As part of the settlement process, Ezypay will deduct the $1000 from Franchisee Gym A's account first before we settle the funds (that Ezypay had collected through billing their customers) to them, and arrange for the $1000 to be settled into the head office/franchisor's account on a monthly basis.

🚧

Important Note:

Partner Invoice needs to be created before any settlement can run for a partner invoice (recipient). This is to ensure there is enough money in the partner invoice (recipient's) wallet to be distributed to the issuers wallet.

The only possible failure for a partner invoice would be due to insufficient funds in the recipient's wallet.

The scope to create the authentication token needs to include a partner (Integrator's will need to contact Ezypay to allow this scope to be enabled)

No tax will be charged using the Partner Invoice between 2 existing Merchants.

NamingDescription
issuerMerchantThe merchant who is requesting for a file transfer using a partner invoice.
recipientMerchantThe merchant who will transfer the amount based on who the issuerMerchant is.
Transaction API senderThe merchant who is sending the funds transfer using the Partner Invoice process.
Transaction API receiverThe merchant who is receiving the money using the Partner Invoice process.

1. Create a Partner Invoice

📘

Prerequisite (Webhook event)

The "issuer" needs to subscribe to the 3 events listed below if they would like to receive the webhook events for Partner Invoices.

  • partner_invoice_created,
  • partner_invoice_paid,
  • partner_invoice_past_due

[POST] https://api-sandbox.ezypay.com/v2/partnerinvoices

API Endpoint Documentation: https://developer.ezypay.com/reference#create-a-partner-invoice

{
  "issuerMerchantId": "{{sub_merchant_id}}",
  "recipientMerchantId": "{{main_merchant_id}}",
  "memo": "Testing payment",
  "items": [
    {
       "amount": {
       "currency": "AUD",
       "value": 2
     },
     "accountingCode":{{Text will appear in the settlement report}},
     "tax": {
       "rate": 0
     },
     "description": "Testing"
    }
  ]
}

{
    "id": "f793fc11-d4bc-4f40-85c3-fe30c17bdd70",
    "documentNumber": "IN0000000000000043",
    "date": "2019-08-16",
    "dueDate": "2019-08-16",
    "status": "PROCESSING",
    "memo": "Testing payment",
    "items": [
        {
            "description": "Testing",
            "amount": {
                "currency": "AUD",
                "value": 2.00,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "96726f58-4357-44b7-b04d-1ea0d48fe8ab",
            "type": "partner_on_demand",
            "accountingCode": {{Text will appear in the settlement report}},
            "additionalDetail": null
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 2.00,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "issuerMerchant": {
        "id": "{{sub_merchant_id}}",
        "name": "Sub Merchant AU",
        "legalName": "Sub Merchant AU"
    },
    "recipientMerchant": {
        "id": "{{main_merchant_id}}",
        "name": "Main Merchant AU",
        "legalName": "Main Merchant AU"
    },
    "createdOn": "2019-08-16T05:56:05.877",
    "countryCode": "AU",
    "partnerSubscriptionId": null
}

2. Get the transaction status

[GET] https://api-sandbox.ezypay.com/v2/billing/transactions?documentId={{PartnerInvoiceGUID}}

{
    "data": [
        {
            "id": {{Ezypay Transaction GUID}},
            "number": null,
            "status": "SUCCESS",
            "createdOn": "2019-12-04T13:57:53.921",
            "failedOn": null,
            "amount": {
                "currency": "AUD",
                "value": 5.00,
                "type": "FIXED_AMOUNT"
            },
            "type": "PARTNER_PAYMENT",
            "source": "wallet",
            "paymentMethodType": "WALLET",
            "paymentMethodDescription": null,
            "failedPaymentReason": null,
            "paymentProviderResponse": {
                "code": null,
                "description": null
            },
            "document": {
                "id": {{Ezypay Invoice Id}},
                "number": "IN0000000000000737",
                "type": "partner_invoice"
            },
            "sender": {
                "id": {{Fund coming out from this merchant wallet}},
                "name": {{Name of the merchant}},
                "type": "MERCHANT"
            },
            "receiver": {
                "id": {{Fund coming in to this merchant wallet}},
                "name": {{Name of the merchant}},
                "type": "MERCHANT"
            },
            "channel": "api"
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

{
    "data": [
        {
            "id": {{Ezypay Transaction GUID}},
            "number": null,
            "status": "FAILED",
            "createdOn": "2019-12-04T12:41:22.233",
            "failedOn": "2019-12-04T12:41:22.228",
            "amount": {
                "currency": "AUD",
                "value": 5.00,
                "type": "FIXED_AMOUNT"
            },
            "type": "PARTNER_PAYMENT",
            "source": "wallet",
            "paymentMethodType": "WALLET",
            "paymentMethodDescription": null,
            "failedPaymentReason": {
                "code": "insufficient_funds",
                "description": "Payment method has insufficient funds at the time of the transaction."
            },
            "paymentProviderResponse": {
                "code": null,
                "description": null
            },
            "document": {
                "id": {{Ezypay Invoice Id}},
                "number": "IN0000000000000059",
                "type": "partner_invoice"
            },
            "sender": {
                "id": {{Fund coming out from this merchant wallet}},
                "name": {{Name of the merchant}},
                "type": "MERCHANT"
            },
            "receiver": {
                "id": {{Fund coming in to this merchant wallet}},
                "name": {{Name of the merchant}},
                "type": "MERCHANT"
            },
            "channel": "api"
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

{
    "data": [
        {
            "id": {{Ezypay Transaction GUID}},
            "number": null,
            "status": "SETTLED",
            "createdOn": "2019-11-13T12:59:38.268",
            "failedOn": null,
            "amount": {
                "currency": "AUD",
                "value": 4.00,
                "type": "FIXED_AMOUNT"
            },
            "type": "PARTNER_PAYMENT",
            "source": "wallet",
            "paymentMethodType": "WALLET",
            "paymentMethodDescription": null,
            "failedPaymentReason": null,
            "paymentProviderResponse": {
                "code": null,
                "description": null
            },
            "document": {
                "id": {{Ezypay Invoice Id}},
                "number": "IN0000000000000058",
                "type": "partner_invoice"
            },
            "sender": {
                "id": {{Fund coming out from this merchant wallet}},
                "name": {{Name of the merchant}},
                "type": "MERCHANT"
            },
            "receiver": {
                "id": {{Fund coming in to this merchant wallet}},
                "name": {{Name of the merchant}},
                "type": "MERCHANT"
            },
            "channel": "api"
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Response received from the webhooks event.

{
  "createdOn": "2019-12-04T03:58:28.471",
  "requestId": "9ec8017f-a926-4ce4-a0e6-08ff3a623c21",
  "merchantId": {{Issuer Merchant Id}},
  "eventType": "PARTNER_INVOICE_CREATED",
  "data": {
    "id": {{Partner Invoice Id}},
    "documentNumber": "IN0000000000000742",
    "date": "2019-12-04",
    "dueDate": "2019-12-04",
    "status": "PROCESSING",
    "memo": "AUD 5 charges",
    "items": [
      {
        "description": "AUD 5 charges",
        "amount": {
          "currency": "AUD",
          "value": 8,
          "type": null
        },
        "tax": {
          "rate": 0
        },
        "id": {{Partner Invoice Item Id}},
        "type": "partner_on_demand",
        "accountingCode": {{Text will appear in the settlement report}},
        "additionalDetail": null
      }
    ],
    "amount": {
      "currency": "AUD",
      "value": 8,
      "type": null
    },
    "totalTax": {
      "currency": "AUD",
      "value": 0,
      "type": null
    },
    "issuerMerchant": {
      "id": {{Funds coming in to this merchant wallet}},
      "name": {{Name of the merchant}},
      "legalName": {{Legal Name of the merchant}}
    },
    "recipientMerchant": {
      "id": {{Funds coming out from this merchant wallet}},
      "name": {{Name of the merchant}},
      "legalName": {{Legal Name of the merchant}}
    },
    "createdOn": "2019-12-04T03:58:27.483",
    "countryCode": "AU",
    "partnerSubscriptionId": null
  }
}

{
  "createdOn": "2019-12-04T03:58:28.679",
  "requestId": "a7c7010d-2331-4aa7-8cb5-9aed0a554376",
  "merchantId": {{Issuer Merchant Id}},
  "eventType": "PARTNER_INVOICE_PAID",
  "data": {
    "id": {{Partner Invoice Id}},
    "documentNumber": "IN0000000000000742",
    "date": "2019-12-04",
    "dueDate": "2019-12-04",
    "status": "PAID",
    "memo": "AUD 5 charges",
    "items": [
      {
        "description": "AUD 5 charges",
        "amount": {
          "currency": "AUD",
          "value": 8
        },
        "tax": {
          "rate": 0
        },
        "id": {{Partner Invoice Item Id}},
        "type": "partner_on_demand",
        "accountingCode": {{Text will appear in the settlement report}},
        "additionalDetail": null
      }
    ],
    "amount": {
      "currency": "AUD",
      "value": 8
    },
    "totalTax": {
      "currency": "AUD",
      "value": 0
    },
    "issuerMerchant": {
      "id": {{Funds coming in to this merchant wallet}},
      "name": {{Name of the merchant}},
      "legalName": {{Legal Name of the merchant}}
    },
    "recipientMerchant": {
      "id": {{Funds coming out from this merchant wallet}},
      "name": {{Name of the merchant}},
      "legalName": {{Legal Name of the merchant}}
    },
    "createdOn": "2019-12-04T14:58:27.836",
    "countryCode": "AU",
    "partnerSubscriptionId": null
  }
}

{
  "createdOn": "2019-12-04T05:55:43.773",
  "requestId": "b16a991c-35c4-4b2a-a9cb-c5c2d9809b8f",
  "merchantId": {{Issuer Merchant Id}},
  "eventType": "PARTNER_INVOICE_PAST_DUE",
  "data": {
    "id": {{Partner Invoice Id}},
    "documentNumber": "IN0000000000000743",
    "date": "2019-12-04",
    "dueDate": "2019-12-04",
    "status": "FAILED",
    "memo": "AUD 300 charges",
    "items": [
      {
        "description": "AUD 300 charges",
        "amount": {
          "currency": "AUD",
          "value": 300
        },
        "tax": {
          "rate": 0
        },
        "id": {{Partner Invoice Item Id}},
        "type": "partner_on_demand",
        "accountingCode": {{Text will appear in the settlement report}},
        "additionalDetail": null
      }
    ],
    "amount": {
      "currency": "AUD",
      "value": 300
    },
    "totalTax": {
      "currency": "AUD",
      "value": 0
    },
    "issuerMerchant": {
      "id": {{Funds coming in to this merchant wallet}},
      "name": {{Name of the merchant}},
      "legalName": {{Legal Name of the merchant}}
    },
    "recipientMerchant": {
      "id": {{Funds coming out from this merchant wallet}},
      "name": {{Name of the merchant}},
      "legalName": {{Legal Name of the merchant}}
    },
    "createdOn": "2019-12-04T16:55:43.757",
    "countryCode": "AU",
    "partnerSubscriptionId": null
  }
}

3. Get Partner Invoice List

[GET] https://api-sandbox.ezypay.com/v2/partnerinvoices?issuerMerchantId={{Issuer_MerchantId}}&recipientMerchantId={{Recipient_MerchantId}}

📘

NOTE

Either issuerMerchantId or recipientMerchantId must be provided.

The type of fields that can be used is listed below:
https://developer.ezypay.com/reference#list-partner-invoices

{
    "data": [
        {
            "id": {{Partner Invoice Id}},
            "documentNumber": "IN0000000000000059",
            "date": "2019-12-04",
            "dueDate": "2019-12-04",
            "status": "PAST_DUE",
            "memo": "AUD 5 charges",
            "items": [
                {
                    "description": "AUD 5 charges",
                    "amount": {
                        "currency": "AUD",
                        "value": 5.00,
                        "type": null
                    },
                    "tax": {
                        "rate": 0.00
                    },
                    "id": {{Partner Invoice Item Id}},
                    "type": "partner_on_demand",
                    "accountingCode": {{Text will appear in the settlement report}},
                    "additionalDetail": null
                }
            ],
            "amount": {
                "currency": "AUD",
                "value": 5.00,
                "type": null
            },
            "totalTax": {
                "currency": "AUD",
                "value": 0.00,
                "type": null
            },
            "issuerMerchant": {
                "id": {{Funds coming in to this merchant wallet}},
      					"name": {{Name of the merchant}},
      					"legalName": {{Legal Name of the merchant}}
            },
            "recipientMerchant": {
                "id": {{Funds coming out from this merchant wallet}},
      					"name": {{Name of the merchant}},
      					"legalName": {{Legal Name of the merchant}}
            },
            "createdOn": "2019-12-04T01:41:18.416",
            "countryCode": "AU",
            "partnerSubscriptionId": null
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Updated over 1 year ago