Skip to main content
POST
/
payment-sessions
Create payment session
curl --request POST \
  --url https://apiv2.example.com/payment-sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "orderId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
  "savePaymentProfile": true,
  "setAsDefaultPaymentProfile": true,
  "hosted": false,
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "metadata": {}
}
'
import requests

url = "https://apiv2.example.com/payment-sessions"

payload = {
    "orderId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
    "paymentProvider": "STRIPE",
    "paymentProfileId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
    "savePaymentProfile": True,
    "setAsDefaultPaymentProfile": True,
    "hosted": False,
    "returnUrl": "https://example.com/order/confirmation",
    "cancelUrl": "https://example.com/order/checkout",
    "metadata": {}
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    orderId: 'd4e5f6a7-b8c9-0123-4567-89abcdef0123',
    paymentProvider: 'STRIPE',
    paymentProfileId: 'e5f6a7b8-c9d0-1234-5678-9abcdef01234',
    savePaymentProfile: true,
    setAsDefaultPaymentProfile: true,
    hosted: false,
    returnUrl: 'https://example.com/order/confirmation',
    cancelUrl: 'https://example.com/order/checkout',
    metadata: {}
  })
};

fetch('https://apiv2.example.com/payment-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apiv2.example.com/payment-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'd4e5f6a7-b8c9-0123-4567-89abcdef0123',
    'paymentProvider' => 'STRIPE',
    'paymentProfileId' => 'e5f6a7b8-c9d0-1234-5678-9abcdef01234',
    'savePaymentProfile' => true,
    'setAsDefaultPaymentProfile' => true,
    'hosted' => false,
    'returnUrl' => 'https://example.com/order/confirmation',
    'cancelUrl' => 'https://example.com/order/checkout',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apiv2.example.com/payment-sessions"

	payload := strings.NewReader("{\n  \"orderId\": \"d4e5f6a7-b8c9-0123-4567-89abcdef0123\",\n  \"paymentProvider\": \"STRIPE\",\n  \"paymentProfileId\": \"e5f6a7b8-c9d0-1234-5678-9abcdef01234\",\n  \"savePaymentProfile\": true,\n  \"setAsDefaultPaymentProfile\": true,\n  \"hosted\": false,\n  \"returnUrl\": \"https://example.com/order/confirmation\",\n  \"cancelUrl\": \"https://example.com/order/checkout\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://apiv2.example.com/payment-sessions")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"orderId\": \"d4e5f6a7-b8c9-0123-4567-89abcdef0123\",\n  \"paymentProvider\": \"STRIPE\",\n  \"paymentProfileId\": \"e5f6a7b8-c9d0-1234-5678-9abcdef01234\",\n  \"savePaymentProfile\": true,\n  \"setAsDefaultPaymentProfile\": true,\n  \"hosted\": false,\n  \"returnUrl\": \"https://example.com/order/confirmation\",\n  \"cancelUrl\": \"https://example.com/order/checkout\",\n  \"metadata\": {}\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://apiv2.example.com/payment-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"orderId\": \"d4e5f6a7-b8c9-0123-4567-89abcdef0123\",\n  \"paymentProvider\": \"STRIPE\",\n  \"paymentProfileId\": \"e5f6a7b8-c9d0-1234-5678-9abcdef01234\",\n  \"savePaymentProfile\": true,\n  \"setAsDefaultPaymentProfile\": true,\n  \"hosted\": false,\n  \"returnUrl\": \"https://example.com/order/confirmation\",\n  \"cancelUrl\": \"https://example.com/order/checkout\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
  "paymentProvider": "STRIPE",
  "savePaymentProfile": true,
  "hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
  "status": "PENDING",
  "metadata": {
    "source": "mobile_app",
    "campaign": "summer_2024"
  },
  "createdAt": "2024-09-29T10:00:00Z",
  "updatedAt": "2024-09-29T10:30:00Z",
  "paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}
{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

Authorizations

​
X-Api-Key
string
header
required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Headers

​
X-Idempotency-Key
string

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Maximum string length: 256

Body

application/json

Request to create a new payment session for processing payment for an order.

​
orderId
string
required

The unique identifier of the order to create a payment session for.

Example:

"d4e5f6a7-b8c9-0123-4567-89abcdef0123"

​
paymentProvider
enum<string>
required

Payment service provider that processes the transaction.

Available options:
STRIPE,
BILLOGRAM
Example:

"STRIPE"

​
paymentProfileId
string

You can add the previously saved payment method to prefill in the payment details.

Example:

"e5f6a7b8-c9d0-1234-5678-9abcdef01234"

​
savePaymentProfile
boolean

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

Example:

true

​
setAsDefaultPaymentProfile
boolean

Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.

​
hosted
boolean

Whether to create a hosted checkout session. When true, a hosted payment page URL is returned for redirecting the customer. When false (default), a payment intent is created for rendering an embedded payment widget.

Example:

false

​
returnUrl
string

The URL to redirect the customer to after payment is completed. Required when hosted is true.

Example:

"https://example.com/order/confirmation"

​
cancelUrl
string

The URL to redirect the customer to if they cancel the payment. Only used when hosted is true.

Example:

"https://example.com/order/checkout"

​
metadata
object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Response

Payment session created successfully

A payment session that wraps the payment process and collects payment information from the user for a specific order.

​
paymentSessionId
string
required

The unique identifier for this payment session.

Example:

"d2e3f4a5-b6c7-8901-2345-012345678901"

​
orderId
string
required

The unique identifier of the order this payment session is for.

Example:

"e3f4a5b6-c7d8-9012-3456-123456789012"

​
paymentProvider
enum<string>
required

Payment service provider that processes the transaction.

Available options:
STRIPE,
BILLOGRAM
Example:

"STRIPE"

​
savePaymentProfile
boolean
required

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

Example:

true

​
hostedUrl
string<uri>
required

The hosted checkout page to redirect the customer to in order to complete payment.

Example:

"https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901"

​
status
enum<string>
required

Current status of a payment session lifecycle.

Available options:
PENDING,
REQUIRES_ACTION,
COMPLETED,
FAILED,
CANCELED,
EXPIRED
Example:

"PENDING"

​
metadata
object
required

Custom key-value pairs for additional payment session information.

Example:
{
  "source": "mobile_app",
  "campaign": "summer_2024"
}
​
createdAt
string<date-time>
required

When this payment session was created.

Example:

"2024-09-29T10:00:00Z"

​
updatedAt
string<date-time>
required

When this payment session was last updated.

Example:

"2024-09-29T10:30:00Z"

​
paymentProfileId
string

The saved payment method to use for this payment (for returning customers).

Example:

"f4a5b6c7-d8e9-0123-4567-234567890123"

​
returnUrl
string

The URL the customer is redirected to after payment completion.

Example:

"https://example.com/order/confirmation"

​
cancelUrl
string

The URL the customer is redirected to if they cancel the payment.

Example:

"https://example.com/order/checkout"