--- title: "Create purchase" method: POST path: "purchases" tags: ["Purchases / Payins"] --- # Create purchase `POST purchases` ## Request - Base URL: `https://payments.air-pay.io` - URL: `https://payments.air-pay.io/purchases` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) 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://`/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. ## Request body - object - `code` string, required: An arbitrary string of the partner’s choosing. Used to identify and correlate Airtm purchases with partner records. Must be unique. - `description` string, required: A text string describing the purchase. This text is displayed to the user when they are confirming the transaction. - `cancel_uri` string, uri: A URL to redirect the user to when they cancel the transaction. - `confirmation_uri` string, uri: A URL to redirect the user to when they confirm the transaction. - `failure_uri` string, uri: Not used. Airtm does not call this URL, use webhooks to be notified when a purchase fails. - `amount` number, 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. - `items` object[], required: An array of the items being purchased/bought. - `description` string - `amount` number - `quantity` number, required ## Response `200` OK - object - `id` string, uuid: Unique id of the transaction - `status` string: Status of the request, can be 'created', 'processing', 'canceled' or 'confirmed'. - `amount` string, 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. - `description` string: A text string describing the purchase. This text is displayed to the user when they are confirming the transaction. - `confirmation_uri` string, uri: A URL to redirect the user to when they confirm the transaction. - `cancel_uri` string, uri: A URL to redirect the user to when they cancel the transaction. - `code` string: An arbitrary string of the partner’s choosing. Used to identify and correlate Airtm purchases with partner records. Must be unique. - `airtm_operation_id` string: Airtm's internal unique id number for the operation. - `created_at` string, date-time: Datetime when the transaction was created. - `updated_at` string, date-time: Datetime of the latest change in status of the transaction. - `airtm_user_id` string, uuid: User id of the user that completed one purchase. - `airtm_user_email` string, email: Email of the user that completed one purchase. - `operation_type` string: Operation type, always 'purchase'. - `failure_uri` string: Not used. Airtm does not call this URL, use webhooks to be notified when a purchase fails. - `failure_reason` string: This populates with the reason the operation failed. - `callback_uri` string: Deprecated. Airtm no longer calls this URL, and new purchase requests that include it are rejected. Use webhooks instead. - `airtm_operation_hash` string: Unique hash for the Purchase operation within the Airtm system. ## Other responses - `403`: Duplicated Code - `500`: Internal Server Error --- [API](https://skmtc.dev/airtm/apis/airtm-enterprise-api-v1.md) - [All operations](https://skmtc.dev/airtm/apis/airtm-enterprise-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/airtm/apis/airtm-enterprise-api-v1/revisions/4e8326a04343?raw)