Zip via the API

To handle Zip via the API directly, follow our quick start guide on direct API integrations, or use the steps below.

​

Create a transactions

To create a Zip transaction, set the method to zippay and the redirect_url to the endpoint of your application that can handle the customer returning once they’ve completed approving the transaction on the Zip site.

See the POST /transactions API endpoint for more details.

If successful, the response of this transaction will include a status set to buyer_approval_pending as well as a payment_method.approval_url.

{
    "type": "transaction",
    "id": "0c41c8df-27f4-480e-97f0-9401558ae25e",
    "status": "buyer_approval_pending",
    "intent": "authorize",
    "payment_method": {
        "type": "payment-method",
        "method": "zippay",
        "mode": "redirect",
        "approval_url": "https://zip.co/checkout?co=c0_abc123&m=aaaa-bbbb-cccc",
       ...
    },
    "method": "zippay",
    ...
}

​

About tokenization

If your Zip account supports recurring payment, then you can pass the store=true parameter to each request to vault a Zip agreement for future use.

Once stored, you can use the vaulted Zip agreement for future transactions without redirecting the buyer to Zip.

​

Handle redirect to Zip

Your application will need to redirect your customer to Zip where they will be required to approve the payment. To do so, redirect the customer to the payment_method.approval_url. After they’ve authenticated themselves, the customer will be redirected back to the redirect_url that you set when creating the transaction.

​

Handle the return to your app

When the customer is redirected back to your app, the transaction status is not known. Your application will therefore need to call our API to get the latest transaction status. To do this, your redirect_url will be appended with the transaction_id.

[redirect_url]?transaction_id=2f37e0d0-5549-42c4-9c5c-e03d5fa97148&transaction_status=capture_succeeded

After you’ve handled the redirect, you can display a message to your customer letting them know the result of the transaction.

​

Fetch the latest status

Finally, after the transaction has been created your application can get the latest details and status using the transaction ID received via the callback to the redirect URL, or on direct callback from the API.

The transaction includes details about the payment method used and the status of the transaction.

{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "status": "authorized",
  "amount": 1299,
  "currency": "AUD",
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "zippay",
    ...
  },
  ...
}