AIairtm
Purchases / Payins

Create purchase

This endpoint will allow you to create a Purchase (Pay-in). In order to complete a Purchase, it must first be created, then the user must be directed to the Airtm website to confirm/checkout the Purchase, at which time they will be redirected to a URL of your choosing. See “Usage” below.

We will redirect the user to either confirmation_uri or cancel_uri with code as query parameter so you can process the Purchase as being either confirmed or cancelled.

Usage

  1. Create a Purchase via an HTTP POST.

  2. Extract the id from the response, and redirect user to: https://<API Host>/checkout/:id User will be redirected for authentication as necessary.

  3. User will confirm or cancel purchase from Airtm’s website.

  4. If confirmed, money will be transferred from user’s Airtm wallet, to partner's Airtm wallet, and redirected to the provided confirmation_uri. If canceled, no money will be transferred, and the user will be redirected to the provided cancel_uri.

Upon confirmation, or cancellation the purchase will be considered completed, and the URL residing at /checkout/:id will no longer function. Therefore, if you wish to complete an identical Purchase, you will need to create a new Purchase, and be provisioned a new id for that Purchase.

The confirmation_uri attribute should not be used for transaction completeness verification, if the URI was requested, it doesn't mean the transaction was completed successfully. Use webhooks to be notified when the purchase is completed, either if it was confirmed, canceled or failed, or check the transaction status using GET /operations/:id before any external movement.

[!tip] The way to emit a purchase refund is to create a payout from your Airtm Partner account and then commit it, this will move money from your Airtm account to your user's Airtm account.

postpurchases

Request

Request body

codestring required

An arbitrary string of the partner’s choosing. Used to identify and correlate Airtm purchases with partner records. Must be unique.

descriptionstring required

A text string describing the purchase. This text is displayed to the user when they are confirming the transaction.

cancel_uristring uri

A URL to redirect the user to when they cancel the transaction.

confirmation_uristring uri

A URL to redirect the user to when they confirm the transaction.

failure_uristring uri

Not used. Airtm does not call this URL, use webhooks to be notified when a purchase fails.

amountnumber required

The total amount in USD of the purchase. This value must correctly correspond to the sum of the amounts associated with each purchase item.

Example request

{
  "code": "ExternalIdentifier01",
  "description": "Test purchase",
  "cancel_uri": "https://your.site/cancel",
  "confirmation_uri": "https://your.site/confirm",
  "failure_uri": "https://your.site/failure",
  "amount": 15,
  "items": [
    {
      "description": "test item 2",
      "amount": 3,
      "quantity": 1
    }
  ]
}

Response

OK

idstring uuid

Unique id of the transaction

statusstring

Status of the request, can be 'created', 'processing', 'canceled' or 'confirmed'.

amountstring float

The total amount in USD of the purchase. This value must correctly correspond to the sum of the amounts associated with each purchase item.

descriptionstring

A text string describing the purchase. This text is displayed to the user when they are confirming the transaction.

confirmation_uristring uri

A URL to redirect the user to when they confirm the transaction.

cancel_uristring uri

A URL to redirect the user to when they cancel the transaction.

codestring

An arbitrary string of the partner’s choosing. Used to identify and correlate Airtm purchases with partner records. Must be unique.

airtm_operation_idstring

Airtm's internal unique id number for the operation.

created_atstring date-time

Datetime when the transaction was created.

updated_atstring date-time

Datetime of the latest change in status of the transaction.

airtm_user_idstring uuid

User id of the user that completed one purchase.

airtm_user_emailstring email

Email of the user that completed one purchase.

operation_typestring

Operation type, always 'purchase'.

failure_uristring

Not used. Airtm does not call this URL, use webhooks to be notified when a purchase fails.

failure_reasonstring

This populates with the reason the operation failed.

callback_uristring

Deprecated. Airtm no longer calls this URL, and new purchase requests that include it are rejected. Use webhooks instead.

airtm_operation_hashstring

Unique hash for the Purchase operation within the Airtm system.

Example response

{
  "id": "5201de5f-03e6-43e1-ba36-bebaf3f429f6",
  "status": "created",
  "amount": "15.00",
  "description": "Purchase test",
  "confirmation_uri": "https://your.site/confirm",
  "cancel_uri": "https://your.site/cancel",
  "code": "ExternalIdentifier01",
  "created_at": "2022-05-25T00:34:30.641Z",
  "updated_at": "2022-05-25T00:34:30.641Z",
  "operation_type": "purchase",
  "callback_uri": "https://your.site/callback"
}

Changes

No recorded changes to this operation across all 1 revision of this API.