Create Transaction

You can use this call to create a new in3 transaction.

Prerequisite

Get an access_token and use it as 'Bearer' token in your request. Find more details here.

Request

POST https://api.pay.cm.com/api/v1/paymentmethods/in3/v1/transactions

Request body examples

These are only some examples of the request body to create a transaction:

{
  "invoice": {
    "reference": "20210623130413",
    "amount": 12000,
    "description": "Order at yourdomain.tld"
  },
  "expiresAt": "2025-01-02T15:04:05Z",
  "consumer": {
    "name": {
      "initials": "A",
      "lastName": "Lopez"
    },
    "phone": "+31695613259",
    "email": "[email protected]",
    "dateOfBirth": "1996-12-31",
    "shippingAddress": {
      "addressedTo": "Scenius",
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "houseNumberSuffix": "A",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland"
    },
    "invoiceAddress": {
      "addressedTo": "Scenius",
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "houseNumberSuffix": "A",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland"
    },
    "business": {
      "name": "CM",
      "cocNumber": "70528500"
    }
  },
  "items": [
    {
      "code": "SDC4/32GB-2ADP",
      "name": "Kingston microSD 32GB",
      "description": "Best seller SD card",
      "unitPrice": 6000,
      "quantity": 2,
      "vatAmount": 1000,
      "vatRate": 20
    }
  ],
  "webhooks": [
    {
      "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
      "events": [
        "FINALSTATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "STATUS_CHANGE"
      ]
    }
  ],
  "returnUrls": {
    "success": "https://yourdomain.tld/order/payment-success.html",
    "cancelled": "https://yourdomain.tld/order/payment-cancelled.html",
    "expired": "https://yourdomain.tld/order/payment-expired.html",
    "failed": "https://yourdomain.tld/order/payment-failed.html"
  }
}

{
  "invoice": {
    "reference": "20210623130413",
    "amount": 12000,
    "description": "Order at yourdomain.tld"
  },
  "expiresAt": "2025-01-02T15:04:05Z",
  "consumer": {
    "name": {
      "initials": "A",
      "lastName": "Lopez"
    },
    "phone": "+31695613259",
    "email": "[email protected]",
    "dateOfBirth": "1996-12-31",
    "shippingAddress": {
      "addressedTo": "Scenius",
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "houseNumberSuffix": "A",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland"
    },
    "invoiceAddress": {
      "addressedTo": "Scenius",
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "houseNumberSuffix": "A",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland"
    },
    "business": {
      "name": "CM",
      "cocNumber": "70528500"
    }
  },
  "items": [
    {
      "code": "SDC4/32GB-2ADP",
      "name": "Kingston microSD 32GB",
      "description": "Best seller SD card",
      "unitPrice": 6000,
      "quantity": 2,
      "vatAmount": 1000,
      "vatRate": 20
    }
  ],
  "webhooks": [
    {
      "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
      "events": [
        "FINALSTATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "STATUS_CHANGE"
      ]
    }
  ],
  "returnUrl": "https://yourdomain.tld/order/payment-completed.html"
}

{
  "invoice": {
    "reference": "20210623130413",
    "amount": 12000,
    "description": "Order at yourdomain.tld"
  },
  "expiresAt": "2025-01-02T15:04:05Z",
  "consumer": {
    "name": {
      "lastName": "Lopez"
    },
    "phone": "+31695613259",
    "email": "[email protected]",
    "dateOfBirth": "1996-12-31",
    "shippingAddress": {
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL"
    }
  },
  "items": [
    {
      "code": "SDC4/32GB-2ADP",
      "description": "Best seller SD card",
      "unitPrice": 6000,
      "quantity": 2,
      "vatAmount": 1000,
      "vatRate": 20
    }
  ],
  "returnUrl": "https://yourdomain.tld/order/payment-completed.html"
}

"Full Request with ReturnURLs" and "Full Request with ReturnURL" are examples where all the request parameters are provided. If returnUrls is defined then customers will be redirected to a different URL depending on the status of the transaction when the payment process is completed. If returnUrl is defined then customers will be redirected to the same URL no matter the status of the transaction when the payment process is completed.

"Minimal Request with ReturnURLs" is an example of the minimal request to create a transaction. This example, is using returnUrls, but you can replace it for returnUrl depending on what is better for your use case.

Parameters

Parameter	Type	Description	Constraints
invoice	invoice Object	Invoice details.
expiresAt	String(RFC3339)	Expiration time.	ISO 8601 date and time.
consumer	consumer Object	Customer details.
items	Array of item objects	Items related to the invoice.
returnUrl	String(2000)	Specifies the URL where your customers will be redirected to when the payment process is completed.	Either `returnUrl` or `returnUrls` must be specified, but not both.
returnUrls	returnUrls Object	Specifies a URL where your customers will be redirected to (per transaction status) when the payment process is completed. For example, your customers will be redirected to `returnUrls.success` when the status of the transaction changes to `SUCCESS`.	Either `returnUrl` or `returnUrls` must be specified, but not both.

Optional parameters

Parameter	Type	Description	Constraints
webhooks	Array of objects	Webhooks enable receiving a web request once a given event occurs.	Find more details here.

Response

{
  "invoice": {
    "reference": "20210623130413",
    "amount": 12000,
    "description": "Order at yourdomain.tld"
  },
  "consumer": {
    "name": {
      "initials": "A",
      "lastName": "Lopez"
    },
    "phone": "+31695613259",
    "email": "[email protected]",
    "dateOfBirth": "1996-12-31",
    "shippingAddress": {
      "addressedTo": "Scenius",
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "houseNumberSuffix": "A",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland"
    },
    "invoiceAddress": {
      "addressedTo": "Scenius",
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "houseNumberSuffix": "A",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland"
    },
    "business": {
      "name": "CM",
      "cocNumber": "70528500"
    }
  },
  "expiresAt": "2025-01-02T15:04:05Z",
  "items": [
    {
      "code": "SDC4/32GB-2ADP",
      "type": null,
      "description": "Best seller SD card",
      "unitPrice": 6000,
      "quantity": 2
    }
  ],
  "action": {
    "redirect": {
      "url": "https://in3.payin3.io/checkout/transaction/de9X1f587bKc3mafbcNu7B441f7r6xSacnY2OK1717be1qda"
    }
  },
  "created": "2024-11-11T14:26:25Z",
  "updated": "2024-11-11T14:26:25Z",
  "id": "f4e09a12-a67a-4417-bab9-9287858eaccd",
  "status": "OPEN",
  "webhooks": [
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "STATUS_CHANGE"
      ]
    },
    {
      "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
      "events": [
        "FINALSTATUS"
      ]
    }
  ],
  "returnUrls": {
    "success": "https://yourdomain.tld/order/payment-success.html",
    "cancelled": "https://yourdomain.tld/order/payment-cancelled.html",
    "expired": "https://yourdomain.tld/order/payment-expired.html",
    "failed": "https://yourdomain.tld/order/payment-failed.html"
  }
}

Parameters

Parameter	Type	Description	Constraints
id	String(36)	Transaction unique identifier.
invoice	invoice Object	Invoice details.	Specified in the request.
consumer	consumer Object	Customer details.	Specified in the request.
expiresAt	String(RFC3339)	Expiration time.	Specified in the request.
items	Array of item objects	Items related to the invoice.	Specified in the request.
status	String	`OPEN` - Transaction has been created. This is the initial status. `PENDING` - Transaction's first instalment payment is in progress. `SUCCESS` - Transaction's first instalment payment successfully paid. `CANCELLED` - Transaction's first instalment payment has been cancelled by your customers. `EXPIRED` - Transaction's first instalment payment has not succeeded; expired. `FAILURE` - Transaction's first instalment payment has not succeeded; unknown reason.
action	action Object	The next action to be performed by you for this transaction. This includes a URL where you should `redirect` your customer to perform the payment.	This parameter is nullable, and it is only available while the transaction is `OPEN`.
created	String(RFC3339)	Creation time.	ISO 8601 date and time.
updated	String(RFC3339	Updated time.	ISO 8601 date and time.
returnUrl	String(2000)	Specifies the URL where your customers will be redirected to when the payment process is completed.	Specified in the request.
returnUrls	Object	Specifies a URL where your customers will be redirected to (per transaction status) when the payment process is completed. For example, your customers will be redirected to `returnUrls.success` when the status of the transaction changes to `SUCCESS`.	Specified in the request.

Optional parameters

Parameter	Type	Description	Constraints
webhooks	Array of objects	Webhooks enable receiving a web request once a given event occurs.	Specified in the request.

Response codes

HTTP status	Description
201	Successful transaction.
4XX	Client error response (See message for details). This response is given when the user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized).
5XX	Server error response (See message for details).