etika Merchant Integration API (1.0.2)

Download OpenAPI specification:Download

API for integrating a store with etika to provide your customers with interest free loans.

Authentication

All requests must include both an api token and a business id.

ApiKeyAuth

API Key for authentication with the API. This must belong to the business that you pass through as part of the request and is required for all requests to the API.

Security Scheme Type API Key
Header parameter name: x-api-key

BusinessId

The ID of the Business that is associated with the merchant and API Key.

Security Scheme Type API Key
Header parameter name: x-pb-business-id

Express Checkout Flow

This flow provisions an order in the etika platform, captures the required customer information to allow etika to make a decision on there application and finally commences the customers loan and settles the payment with the merchant.

  1. Merchant calls the Get Products endpoint to retrieve etika order limits, possibly as part of an asynchronous scheduled background process.
  2. Merchant stores these minimum and maximum order values server-side.
  3. Separately, at the checkout, Merchant uses the stored etika minimum and maximum order values to determine if etika should be presented as an available payment method.
  4. Merchant calls the Create order endpoint to retrieve an etika order token.
  5. Merchant uses the token to direct the Consumer through the etika express checkout flow https://portal.au.etika.com/checkout/express/#/?oid={orderToken}.
  6. Consumer completes the etika express checkout flow and is returned to the Merchant website.
    • If the Consumer clicks confirm, they will be returned to the redirectConfirmUrl provided in the Create order request.
    • If the Consumer clicks cancel, they will be returned to the redirectCancelUrl provided in the Create order request.
    • If the Consumer application is DECLINED and the click continue, they will be returned to the redirectDeclinedUrl provided in the Create orderrequest.
    • If the merchant is able to fulfil the order, the merchant calls the Create Payment endpoint to capture the payment.
  7. Payment status (APPROVED or DECLINED) is only known once Create Payment has been completed.
    • If the payment was approved by etika, the Merchant presents the Consumer with an order confirmation/receipt page.
    • If the payment was declined by etika, the Merchant presents an appropriate message to the Consumer at the checkout

Idempotency

When creating/updating a resource using the API, all POST/PUT/PATCH actions can be initiated with a x-pb-request-id header with a unique string for that request.

Any request that returns a 2XX status code will only be created/updated once, and can be safely repeated for at least 20 minutes. A response that returns a 5XX but is expected to return a 2XX and was initiated with a x-pb-request-id header, can safely be repeated until a 2XX status code is recieved.

We recommend that a GUID or other high entropy value (such as a SHA-1 hash) is used to decrease the chances of a collision.

Configuration

Health check

A health check endpoint to allow dependant services to check the status of the service. If the service is healthy, a 200 status code will be returned. Any other response is considered unhealthy.

This can be used to verify that the system is active and ready to receive requests. This endpoint is throttled to one request every 10 seconds but can be called as part of your monitoring if required.

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

Get Products

Fetch Products of the requesting tenant. Lists available products that can be provided by the corresponding business and api-token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Orders

Create Order

Creates an order based on the provided details. This is the first step in allowing your customer to checkout with etika. Calling this endpoint will return a token that can later be used to accept the payment.

header Parameters
x-pb-request-id
string
Example: ba8e486b-41fa-48d5-8bf3-979c3fe08131

Idempotency token. See how we handle idempotent requests for more information.

Request Body schema: application/json
required
object

The total of this order including shipping, taxes, and after applying all discounts.

object

The total taxes on this Order.

object

The cost of shipping on this Order

product
required
string <= 255 characters
Default: "DEFAULT"
Value: "DEFAULT"

The type of payment product that is going to be offered to your customer as part of their checkout experience.

See your merchant portal for information on what products are available to you.

object

The consumer that is submitting this order.

object

The billing address nominated by the consumer.

object

Shipping address of the consumer. This is required primarily to assist with dispute resolution.

required
object (MerchantMeta)

Details about the order provided by the merchant.

required
Array of objects (Item) non-empty

A list of line items comprising this order.

Array of objects (Discount)

A list of discounts that were applied to this order

Responses

Request samples

Content type
application/json
Example
{
  • "product": "DEFAULT",
  • "totalAmount":
    {
    },
  • "items":
    [
    ],
  • "merchant":
    {}
}

Response samples

Content type
application/json
{
  • "token": "9e1ea67a-cc03-4d5e-905d-2e89a4dd3042",
  • "expires": "2029-01-01T12:00:00.000Z"
}

Get Order

Fetches the order based on the token

path Parameters
token
required
string
Example: f353a9e0-c32a-11e9-a28d-6bc050273bae

The token for the Payment

Responses

Response samples

Content type
application/json
{
  • "product": "BNPL",
  • "consumer":
    {
    },
  • "billing":
    {
    },
  • "shipping":
    {
    },
  • "items":
    [
    ],
  • "discounts":
    [
    ],
  • "merchant":
    {},
  • "taxAmount":
    {
    },
  • "shippingAmount":
    {
    },
  • "totalAmount":
    {
    },
  • "token": "9e1ea67a-cc03-4d5e-905d-2e89a4dd3042",
  • "expires": "2029-01-01T12:00:00.000Z"
}

Payments

Create Payment

Create a payment from an existing Order. This action can only be taken after the user has returned from confirming the Order by logging into their etika account otherwise the request will be denied.

header Parameters
x-pb-request-id
string
Example: ba8e486b-41fa-48d5-8bf3-979c3fe08131

Idempotency token. See how we handle idempotent requests for more information.

Request Body schema: application/json
token
required
string <guid>

A unique token that is returned when creating an order and can be used to confirm payment, after the consumer has been approved for the loan, for the associated order.

Responses

Request samples

Content type
application/json
{