Online API Spec (v0.4.1)

Download OpenAPI specification:Download

Change Log

v0.4.1

  • CheckoutPaymentMethodTypes endpoint to only use PublishableKey.

v0.4

  • Removed mid from CreatePaymentIntent request, PaymentIntent, Payment entities.

v0.3.3

  • Update confirm PI examples to display fields returned with publishableKey

v0.3.2

  • Update customer_message description

v0.3.1

  • Add customer_message to PI error payload

v0.3.0

  • Support for creating Refunds.

v0.2.2

  • revert v0.2.1

v0.2.1

  • Increase create payment intent max amount to 100k

v0.2.0

  • Support PayPal payment method
  • Better docs PaymentIntent statuses

v0.1.2

  • Fixed publishable key documentation

v0.1.1

  • Fixed up documentation for Payment Intents

v0.1.0

  • Initital Payment Intents documentation
  • Removed Payments and Refunds

v0.0.1

  • Initial version with:
    • Payments (Create, List, Get)
    • Refunds (Create, List, Get)

Versioning

All requests to this API will receive the current default version (current v1) if no Accept-Version request header is provided. We encourage you to explicitly set this version via the Accept-Version header.

  Accept-Version: v1

Request Headers

The below table summarises the request headers this API expects for all end points:

Header name Header value Required
Accept-Version v1 No
Authorization ApiKey [ApiKey] Yes
Authorization PublishableKey [PublishableKey] Only for Get/Confirm Payment Intent
Payment-Intent-Client-Secret [PaymentIntentClientSecret] Only for Get/Confirm Payment Intent
Idempotency-Key [idempotencyKey] Only for Confirm Payment Intent

Example:

curl  -H "Authorization: ApiKey eefsdfdsdb1631c4746fe41e123ee10ebe69b9f5e==" \
      -H "Accept-Version: v1" \
      https://api[-sb].<bank-specific-domain.com>/online/payment-intents

Response Headers

Each API request is associated with a request ID available in the X-Request-ID response header. This value is created by the API and uniquely identifies your request. If you need to contact us to trouble shoot a scenario please include this request ID in your communication.

This value is safe and recommended to log

Pagination

All list API end points share a common structure, taking at least these two parameters: page_size, next_page_token

List query string parameters

  • page_size optional default is 10. It limits the number of items to be returned, between 1 and 100

  • page_token optional default to first page. It represents the pagination token to retrieve the next page of result.

    To retrieve the next page of results, client shall pass the value of response's meta.next_page_token in the subsequent list call (in the request message's page_token field)

List response payload

  • data array of items
  • meta where the response pagination data will be centralised
    • next_page_token represents the pagination token to retrieve the next page of results. If omitted, it means no further results for the request

Rate Limits

This API will allow up to 20 requests per seconds per IP.

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. Idempotency is web API principle to apply same operation multiple times without changing the result, so it's always safe to retry as long as server stores the key. Its always recommended to use this for applicable POST requests, to better handle intermittent failures or when an API call is disrupted in transit and you do not receive a response. For example, if a request to confirm a payment intent does not respond due to a network connection error, you can retry with guarantee that single payment will be made.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request. This idempotency key should be a unique value generated by the client with a maximum of 64 characters. Use an algorithm that generates a value with enough randomness, we suggest using V4 UUID(preferred) or another random string with enough entropy to avoid collisions. If optional(although highly recommended) idempotency key is missing from POST request, we still go ahead and confirm the payment.

curl https://api.<bank-specific-domain>.com/online/payment-intents/{id}/confirm \
-H ... other headers ...
-H "Idempotency-Key: 4c190442-2b42-49bd-b6d1-1b2261f2ecf1" \
-d ... request data parameters ...

The idempotency key is valid for 24 hours from the first submission of the request. This means you can use the idempotency key to safely retry a request for 24 hours without fear of performing the same action twice. While using the same idempotency key incoming request parameters cannot be changed.

Retries and exponential backoff

With idempotency in place, retries are expected to follow "exactly once" semantics and give same result, but we also expect clients to use some kind of exponential backoff as they see errors as there might be some genuine server downtime or incident going on.

Expected Idempotency Errors

Error Code HTTP Status Description Resolution
idempotency_key_request_mismatch 400 The idemepotency key does not match the original request data. Please use a new idempotency key.
request_in_flight 409 An existing request with this idempotency key is still in flight. Please wait for it finish.

Errors

The API uses conventional HTTP status codes to indicate the success or failure of the API call.

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate a client error that failed given the information provided.
  • Codes in the 5xx range indicate an error with our servers. Upon receiving 500 errors please quote the returned X-Request-ID value in the response header when asking for assistance.

All API endpoints include an error attribute in their response body when the request fails.

A typical error response has the below schema.

  • error.code, error.customer_message and errors.fields are optional.
  • errors.fields is mostly found in 400 HTTP error to help targeting which field(s) is causing the error
  • errors.customer_message is ONLY found in 400 HTTP payment error, as an advice to customer
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request",
    "customer_message": "Some optional payment error detail"
    "fields": [
      {
        "field": "transaction_ts_ms_gteq",
        "description": "Missing field"
      },
      {
        "field": "transaction_ts_ms_lteq",
        "description": "Missing field"
      }
    ]
  }
}

Global Error Codes

We have provided a list of global error codes that can be used in a similar way to the http status.

We recommend that the status takes priority for all of these global error codes but these can be used to further show that the error was caused by the application rather than some other issue like network.

Error Code HTTP Status Description Resolution
generic_bad_request 400 The provided request is invalid. Check all fields provided are valid.
invalid_request 400 The provided request is invalid. Check the invalid fields in error.fields property in the error payload, and ensure that the format and value of all fields you passed in are valid.
request_body_should_be_omitted 400 A request body was provided. This end point does not support body payload. Please remove it.
json_body_invalid 400 Request body contains badly-formed JSON. Check the syntax error in the JSON request body and ensure that the request is in the correct JSON format.
accept_version_header_invalid 400 The provided Accept-Version request header value is invalid. Ensure the value matches the supported versions.
api_key_missing 400 Missing API key in Authorization header (e.g. 'Authorization: ApiKey YOUR_KEY'). Ensure you provide an API key in request header.
api_key_invalid 401 An invalid API key has been provided. Ensure you pass a valid API key.
generic_unauthorized 401 The request was not authorized. Check your authentication header to ensure it is correct.
generic_forbidden 403 You are forbidden from performing the action. Ensure the action you are performing is against a target you have access to.
generic_not_found 404 The resource was not found. Ensure resource you are performing the action against exists.
generic_conflict 409 The resource is in a conflicting state. Check the resource and try again.
generic_unprocessable_entity 422 There was a pre-condition that failed on the resource. Check the resource and try again.
generic_too_many_requests 429 Too many requests have been received in a short period of time. Wait a moment and try again.
generic_request_cancelled 499 The original request has been cancelled. Allow the request to complete.
generic_not_implemented 501 The requested functionality has not yet been implemented. Check the spec to ensure the functionality is ready for use.
generic_service_unavailable 503 The service is currently unavailable. Wait a moment and try again.
generic_gateway_timeout 504 The service has timed-out trying to process your request. Wait a moment and try again.

Refund Error codes

Below is a list of possible error codes that can be returned for Refund operations, along with additional information about how to resolve them.

Error Code HTTP Status Description Resolution
refund_declined 400 The Refund has been declined for an unknown reason. Retry after some time.
amount_exceeds_refundable_amount 400 The requested refund amount exceeds the Payment's refundable amount. Check the amount_refunded value for the Payment and make sure not to request a refund in excess.
payment_already_refunded 400 The Payment has already been fully refunded. No resolution required, further refunds are not possible.
payment_not_refundable 400 The Payment is not refundable for a generic reason. Check the message field in the response for more context.

Payment Error Codes

Error Code HTTP Status Description Resolution
generic_declined 400 The payment has been declined for an unknown reason. Payment has been declined due to unkown reason, retry after sometime.
insufficient_funds 400 Insufficient funds to complete the purchase. Payment method used does not have enough funds, change and retry.
timeout 400 The server timed out processing the payment, please retry. Payment processing timed out, retry after sometime.
card_expired 400 The card has expired. The card used for purchase is expired, use different card and retry.
card_number_invalid 400 The card number is incorrect. The card number used for purchase is invalid, use correct card number and retry.
amount_invalid 400 The payment amount is invalid, or exceeds the amount that is allowed. Payment amount entered is invalid, use valid amount and retry.
card_scheme_not_accepted 400 The card scheme is not accepted. Card scheme used in not supported, use supported scheme and retry.
card_token_already_used 400 The card token has already been used. Card token is already used, tokenize again and retry.

Authentication

SecretApiKey

The online API secret key can be self-generated in the Merchant Dashboard.

This key should only be used for backend to backend communication and should not exposed publicly.

This is the recommended default usage of this API.

Usage format:

Authorization: ApiKey <YOUR_SECRET_API_KEY>
Security Scheme Type HTTP
HTTP Authorization Scheme ApiKey

PublishableKey

For a small number of end points, the online API support calls with a publishable key (self-generated in the Merchant Dashboard).

That is the only key that could be used client side. It identifies your merchant account.

This key can be use when calling client side PaymentIntent endpoints along with the PaymentIntent's client_secret

Example: ConfirmPaymentIntent end point

Usage format:

Authorization: PublishableKey: <YOUR_PUBLISHABLE_KEY>
Security Scheme Type HTTP
HTTP Authorization Scheme PublishableKey

CheckoutPaymentMethodTypes

List checkout payment method types

Retrieves all enabled CheckoutPaymentMethodType(s) that the customer could choose to use at checkout time.

If using a Publishable Key client side, the client_secret of the PaymentIntent must be provided.

Authorizations:
query Parameters
payment_intent_id
required
string
Example: payment_intent_id=16eca704-612b-4eac-a502-3dc7b9059888

The payment intent ID.

header Parameters
Payment-Intent-Client-Secret
string
Example: 16eca704-612b-4eac-a502-3dc7b9059888

The client secret.

Required when using a Publishable Key to retrieve the payment

Responses

200

Success

get /checkout-payment-method-types

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/online/checkout-payment-method-types

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/online/checkout-payment-method-types

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

PaymentIntents

Create a PaymentIntent

Create one as soon as the price is known (on your order checkout page), ideally before customer press "Pay".

Always call this endpoint server side with your Secret Key

Then use returned payment_intent.client_secret to confirm the PaymentIntent client side with our SDK).

After the call, the PaymentIntent status will be one of the following:

  • REQUIRES_PAYMENT_METHOD: Populate a payment_method when confirming the PaymentIntent.
Authorizations:
Request Body schema: application/json
amount
required
integer [ 100 .. 1000000 ]

The amount in the currencies lowest denomination

currency
required
string
Value: "AUD"

The currency associated with the amount

Responses

200

Success

400

Invalid Request

401

Unauthenticated

403

Forbidden

post /payment-intents

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/online/payment-intents

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/online/payment-intents

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "amount": 100,
  • "currency": "AUD"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Confirm a PaymentIntent

Confirm a PaymentIntent when customer is ready to make a payment with a given PaymentMethod

After the call, the PaymentIntent status will be one of the following:

  • SUCCEEDED if the Payment is authorized and captured successfuly and no more customer actions are required.
  • REQUIRES_PAYMENT_METHOD if the payment using the current PaymentMethod failed, and customer should try with another PaymentMethod.
  • REQUIRES_ACTION: if the Payment requires additional customer actions to complete the authorization. eg authenticate customer via 3rd party website redirect or 3DS. Check "next_action" response attribute for details.
  • PROCESSING: likely for PaymentMethod types where the payment status is not immediate. Query the PaymentIntent again.

Below is a list of possible payment error codes that can be returned by confirm payment intent operation. See payment errors and global errors for more details and resolution.

Error Code HTTP Status
generic_declined 400
insufficient_funds 400
timeout 400
card_expired 400
card_number_invalid 400
amount_invalid 400
card_scheme_not_accepted 400
card_token_already_used 400

Note : This endpoint can only be called client side via our SDK using a Publishable Key

Authorizations:
header Parameters
Payment-Intent-Client-Secret
string
Example: 16eca704-612b-4eac-a502-3dc7b9059888

The client secret.

Idempotency-Key
string
Example: 4c190442-2b42-49bd-b6d1-1b2261f2ecf1

This is an optional header field used to carry unique value generated by the client, which is used by server to recognize subsequent retries. Its preferred to use high entropy keys like uuid. Provide an additional Idempotency-Key: <key> header to the request for idempotency. More details here

Request Body schema: application/json
payment_method_data
object (payment_method_data)

Details to create a payment method.

use_sdk
boolean

Set to true when the PaymentIntent next_action is to be handled by our SDK (example 3rd party payment authentication handle by our JS SDK).

Responses

200

Success

400

Failure

post /payment-intents/{payment_intent_id}/confirm

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/online/payment-intents/{payment_intent_id}/confirm

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/online/payment-intents/{payment_intent_id}/confirm

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "payment_method_data":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Get a PaymentIntent

Retreive a single payment intent

If using a Publishable Key client side, the client_secret of the PaymentIntent must be provided. Only a subset of attributes will be returned in that case, see properties with "(RETRIEVABLE WITH PUBLISHABLE KEY)".

path Parameters
payment_intent_id
required
string
Example: 16eca704-612b-4eac-a502-3dc7b9059888

The PaymentIntent id

header Parameters
Payment-Intent-Client-Secret
string
Example: 16eca704-612b-4eac-a502-3dc7b9059888

The client secret.

Only required if a Publishable Key is used (instead of a Secret Key) to retrieve the payment

Responses

200

Success

get /payment-intents/{payment_intent_id}

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/online/payment-intents/{payment_intent_id}

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/online/payment-intents/{payment_intent_id}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Refunds

Create a refund

Create a Refund for an existing payment that has not yet been fully refunded.

Always call this endpoint server side with your Secret Key.

Error codes

Below is a list of possible error codes that can be returned for this operation. See Refund Error Codes and Global Error Codes for more details.

Error Code HTTP Status
invalid_request 400
refund_declined 400
amount_exceeds_refundable_amount 400
payment_already_refunded 400
payment_not_refundable 400
Authorizations:
Request Body schema: application/json
One of
  • Refund By Payment Intent
  • Refund By Payment
payment_intent_id
string

The ID of the PaymentIntent to refund.

amount
integer >= 1

The amount to refund in the Payment currency's lowest denomination.

If not specified this will default to the amount on the Payment not already refunded. Both full and partial refunds are supported.

Responses

200

Success

400

Fail

401

Unauthenticated

403

Forbidden

404

Not Found

post /refunds

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/online/refunds

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/online/refunds

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "payment_intent_id": "df6c9216-6eb2-4971-9d15-7dfd46e04d8b",
  • "amount": 100
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}