This page details the V2 FlipPay API in a general use context.

For information about a specific product (e.g. configuration of product fields), refer to the integration guide available within the FlipPay web portal for authorised users.

If you need access to V1 documentation, or have any other questions, send an email to integrations@flippay.com.au

Quick tips

There are two environments available:

• Live (production environment)
  • App (for merchants): app.flippay.com.au
  • App (for integrated partners): introducer.flippay.com.au
  • API endpoint: app.flippay.com.au/api/v2
• Demo (customer-facing sandbox)
  • App (for merchants): demo.flippay.com.au
  • App (for integrated partners) demointroducer.flippay.com.au
  • API endpoint: demo.flippay.com.au/api/v2

Environments are entirely separate - different accounts are required on each environment, and different configurations/IDs will be available in each environment unless you're otherwise advised (i.e. don't assume to use a demo product in the live environment, it won't work!)

Formats & protocols:

• All communication is over HTTPS
• Data is sent and received as JSON, all fields are sent as JSON string unless explicitly noted otherwise (we format validate various strings where necessary, keep it simple otherwise)
• Dates & times are returned in UTC
• All files provided via API must be encoded in base64, where files are detected as incorrectly encoded, you will be required to correct your integration
• Any url included in a request must be validly formed, otherwise will be rejected/ignored (applies to all instances of a url field)
• Any email address included in a request must be validly formed, otherwise will be rejected/ignored (applies to all instances of an email field)
• phone means an Australian phone number, all phone numbers included in a request must be validly formed, otherwise will be rejected/ignored (applies to all instances of a phone field)
  • 10 digits and starts with 02, 03, 04, 07, 08 ... or 1300, 1800
  • OR 6 digits and starts with 13
• mobile means an Australian mobile number, all mobile numbers included in a request must be validly formed, otherwise will be rejected/ignored (applies to all instances of a mobile field)
  • 10 digits starting with 04
  • Designated separately as this field will typically be used to send SMS

Dealing with products:

• Always refer to the integration guide (accessed via the FlipPay web portal) for the products enabled on your account, guide contains contextual tips and information, product field specifications and details on special settings or conditions (e.g. disbursement methods) relative to your product or use case
• Changes to products & product fields are considered as breaking changes (i.e. rare, planned, communicated)
• You can only transact on products enabled on your account and on the merchant account you're transacting with (if you're an integrated partner)

General info:

• Payment requests cannot be edited once created, other than some products allowing product fields to be updated
• Payment requests will expire after 90 days if not actioned prior - once expired, they'll move to a cancelled status and cannot be revived
• You can cancel a payment request before it has been activated, but not afterwards
• You can only refund card transactions created on a pay-now payment request, no other transactions or request types support refunds
• Logo images should be sized <= 62 pixels high (width relative, but ideally similar), otherwise they may not display cleanly on payment pages
• Where fields are “required” and provided in an invalid format, the request will be rejected with a 4xx code
• Where fields are “optional” and provided in an invalid format, those fields will be discarded and the request will be accepted with a 200 code

Testing:

• Use your own mobile and email, or ones you control ... if you spam random people, your account will be locked
• Identity verification is disabled by default in the test merchant account you're allocated
  • If you enable it (login to merchant web portal to do so), you'll need to contact integrations@flippay.com.au for valid test data (not recommended or required for most use cases)
  • When disabled, enter any data to proceed (just need to populate required fields, content won't be checked against verification service)
• OTP via mobile/email is disabled by default in the test merchant account you're allocated (you can enable if you want, login to the merchant web portal to do so), so to test:
  • Continue to enter valid mobile/email details (these will not receive an OTP, but will be used for later actions relative to the process you're testing)
  • Enter "111111" (6 x "1") as the OTP
• Disbursements still need to reference a valid accountId on the test merchant account you're allocated, OR you can use any BSB/account or BPAY if those options are enabled on the product
• Card payments must be tested using these details (live cards are not accepted in the non-live environments):
  • Visa 4111 1111 1111 1111 (Success)
  • Visa 4242 4242 4242 4242 (Failure)
  • Mastercard 5555 5555 5555 4444 (Success)
  • Mastercard 5105 1051 0510 5100 (Failure)
• Some endpoints will include a payload in the 200 response, make sure to check them for warnings (non-critical issues that can confuse testing if you're not aware)

If you have any questions, don't hesitate to contact integrations@flippay.com.au for some help. Please do include as much information as you can - request/response payloads are best, url/endpoint you're using, any relevant IDs (merchant, payment request, etc)

Good luck!

"Pay later" covers payment requests sent from a merchant to one of the merchant's customers, where that request is enabled with a financial product (e.g. BNPL, delayed payment, loan, etc) in addition to a standard "pay now" option. Payment requests created via this mode generate their own unique payment page, presenting the payment options available (as onboarded for the merchant) and customisation options for the merchant to utilise. When creating a pay later request, the initiator can:

• Offer multiple payment options (products)
• Nominate bank accounts or other targets to disburse the payment to (subject to product configuration)
• Send the payment page via FlipPay or just generate the url and send it yourself
• Customise and brand the payment page with logos, personal messages, contact details and business information in the footer
• Attach files to a payment request
• Direct notifications on the request's status changes via webhook and email

Key points to note:

• Refer to the quick tips at the top of page!
• The reference provided will appear in the merchant's remittance advice (use that field wisely)
• Unless noted in the integration guide for your product, all products will only disburse to a merchant's bank account that has been verified during onboarding and alllocated an accountId; you can use the accountId, or provide bsb/account number for the same account (and it will be validated as such)
• Unless noted in the integration guide for your product, all products will automatically offer a "pay now" option along side any pay later product, when using this endpoint
• Whenever an ID verification is required, a customer will have a maximum of 3 attempts to get this right ... after that, the pay later product will be disabled on this payment request (be aware that such a customer is unlikely to receive funding approval on subsequent requests), there are no excceptions here

Notifications are generated when the payment request moves through statuses, pay later requests may utilise any of the statuses below (refer to your product integration guide for specifics, and guidance as to "does this matter to me"):

• pending - request has been generated but not yet accessed by the customer
• submitted - request has been submitted by the customer and diverted for manual assessment
• active - request has been approved and payment option is active (merchant will receive disbursement next day)
• declined - request has been declined out of manual approval (terminal status, can't be revived)
• cancelled - request has been cancelled by integrated partner, merchant or FlipPay
• complete - request has been completely paid (customer has completed payment agreement)

Sample notification payload (when sent via webhook):

{
  "prId": "PR-1234-5678",
  "status": "active"
}

"Pay now" covers payment requests sent from a merchant to one of the merchant's customers, where that request is enabled ONLY for the customer to pay the merchant in full, with no alternative payment options (e.g. BNPL, delayed payment, loan, etc). These payment requests operate similarly to "pay later", with the following exceptions:

• Pay now requests will only disburse into a bank account verified on the merchant account
• There is no submitted, active or declined status returned - only pending, cancelled or complete

The direct endpoints enable B2B requests for funding between onboarded entities and FlipPay (e.g. B2B invoice financing, equipment finance, etc). These payment requests will not generate a payment page, but otherwise will operate similarly to a pay later request between a merchant and customer, with the following exceptions:

• Only one product can be enabled on a direct request
• Depending on the product used, direct requests can be disbursed to a bank account enabled on the merchant account, or an external bank account (refer to the integration guide available within the FlipPay web portal)
• Repayment of the request will typically be via merchant (either the merchant pays FlipPay via EFT manually or a direct debit on the disbursement account is enacted, per the product configuration)

These services are used to onboard new merchants to FlipPay via integrated partners. Key points to note:

• Integrated partners are enabled for defined products per their agreement with FlipPay, these products are automatically enabled on approved merchant accounts initiated by the integrated partner.
• Approved merchant accounts are automatically linked with the integrated partner who initiated the onboarding request (no need to use the separate link services if you create the onboarding request).
• Onboarding requests require an OTP to access, sent to the email address provided when the request was initiated (ensure the merchant provides a suitable email address).
• The "onboardingID" provides a unique reference for a specific onboarding request, and is not the same as a "merchantID".
• The "merchantID" is created when a merchant account is approved, and is included in the notification back to the integrated partner so that you can match the initial onboarding request with the later approved account (and then enable and enable FlipPay services for the Merchant).

These services are used to manage links between accounts of integrated partners and merchants.

Key points:

• When a new merchant is onboarded to FlipPay via an integrated partner, the partner and merchant accounts are automatically linked
• When an existing merchant on FlipPay joins an integrated partner, the partner should request a link to the merchant account instead of onboarding (as the merchant is already onboarded)
  • Link requests generate an alert inside the merchant's FlipPay web portal, where an authorised user can accept the request to link accounts
• Both the merchant and integrated parter can remove the link at any time
• An active link between accounts is required for an integrated partner to transact on a merchant account

General use functions to support integrated merchants and partners.