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-business-id

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
{
  • "token": "9e1ea67a-cc03-4d5e-905d-2e89a4dd3042"
}

Response samples

Content type
application/json
{
  • "id": "f353a9e0-c32a-11e9-a28d-6bc050273bae",
  • "created": "string",
  • "status": "APPROVED",
  • "order":
    {