Create payment profile session
curl --request POST \
--url https://apiv2.example.com/payment-profiles/sessions \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"orderId": "9f8e7d6c-5b4a-3210-9876-543210987654",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"cancelUrl": "https://example.com/order/checkout",
"setAsDefaultPaymentProfile": false,
"metadata": {}
}
'import requests
url = "https://apiv2.example.com/payment-profiles/sessions"
payload = {
"orderId": "9f8e7d6c-5b4a-3210-9876-543210987654",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"cancelUrl": "https://example.com/order/checkout",
"setAsDefaultPaymentProfile": False,
"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: '9f8e7d6c-5b4a-3210-9876-543210987654',
paymentProvider: 'STRIPE',
returnUrl: 'https://example.com/order/confirmation',
cancelUrl: 'https://example.com/order/checkout',
setAsDefaultPaymentProfile: false,
metadata: {}
})
};
fetch('https://apiv2.example.com/payment-profiles/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-profiles/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' => '9f8e7d6c-5b4a-3210-9876-543210987654',
'paymentProvider' => 'STRIPE',
'returnUrl' => 'https://example.com/order/confirmation',
'cancelUrl' => 'https://example.com/order/checkout',
'setAsDefaultPaymentProfile' => false,
'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-profiles/sessions"
payload := strings.NewReader("{\n \"orderId\": \"9f8e7d6c-5b4a-3210-9876-543210987654\",\n \"paymentProvider\": \"STRIPE\",\n \"returnUrl\": \"https://example.com/order/confirmation\",\n \"cancelUrl\": \"https://example.com/order/checkout\",\n \"setAsDefaultPaymentProfile\": false,\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-profiles/sessions")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"orderId\": \"9f8e7d6c-5b4a-3210-9876-543210987654\",\n \"paymentProvider\": \"STRIPE\",\n \"returnUrl\": \"https://example.com/order/confirmation\",\n \"cancelUrl\": \"https://example.com/order/checkout\",\n \"setAsDefaultPaymentProfile\": false,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.example.com/payment-profiles/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\": \"9f8e7d6c-5b4a-3210-9876-543210987654\",\n \"paymentProvider\": \"STRIPE\",\n \"returnUrl\": \"https://example.com/order/confirmation\",\n \"cancelUrl\": \"https://example.com/order/checkout\",\n \"setAsDefaultPaymentProfile\": false,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"orderId": "44567801-a504-4f09-8089-31ea78bc239b",
"paymentProvider": "STRIPE",
"status": "PENDING",
"hostedUrl": "https://payments.example.com/setup/69321a62-f1fe-461f-8761-a19ae6587bb2",
"metadata": {
"source": "mobile_app",
"campaign": "summer_2024"
},
"createdAt": "2024-09-29T10:00:00Z",
"updatedAt": "2024-09-29T10:30:00Z"
}{
"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>"
}Payment Profile Sessions
Create payment profile session
Create a new payment profile session to set up and save a payment method for future use.
Used for zero-cost orders where payment collection isn’t needed but payment method setup is required.
POST
/
payment-profiles
/
sessions
Create payment profile session
curl --request POST \
--url https://apiv2.example.com/payment-profiles/sessions \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"orderId": "9f8e7d6c-5b4a-3210-9876-543210987654",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"cancelUrl": "https://example.com/order/checkout",
"setAsDefaultPaymentProfile": false,
"metadata": {}
}
'import requests
url = "https://apiv2.example.com/payment-profiles/sessions"
payload = {
"orderId": "9f8e7d6c-5b4a-3210-9876-543210987654",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"cancelUrl": "https://example.com/order/checkout",
"setAsDefaultPaymentProfile": False,
"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: '9f8e7d6c-5b4a-3210-9876-543210987654',
paymentProvider: 'STRIPE',
returnUrl: 'https://example.com/order/confirmation',
cancelUrl: 'https://example.com/order/checkout',
setAsDefaultPaymentProfile: false,
metadata: {}
})
};
fetch('https://apiv2.example.com/payment-profiles/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-profiles/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' => '9f8e7d6c-5b4a-3210-9876-543210987654',
'paymentProvider' => 'STRIPE',
'returnUrl' => 'https://example.com/order/confirmation',
'cancelUrl' => 'https://example.com/order/checkout',
'setAsDefaultPaymentProfile' => false,
'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-profiles/sessions"
payload := strings.NewReader("{\n \"orderId\": \"9f8e7d6c-5b4a-3210-9876-543210987654\",\n \"paymentProvider\": \"STRIPE\",\n \"returnUrl\": \"https://example.com/order/confirmation\",\n \"cancelUrl\": \"https://example.com/order/checkout\",\n \"setAsDefaultPaymentProfile\": false,\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-profiles/sessions")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"orderId\": \"9f8e7d6c-5b4a-3210-9876-543210987654\",\n \"paymentProvider\": \"STRIPE\",\n \"returnUrl\": \"https://example.com/order/confirmation\",\n \"cancelUrl\": \"https://example.com/order/checkout\",\n \"setAsDefaultPaymentProfile\": false,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.example.com/payment-profiles/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\": \"9f8e7d6c-5b4a-3210-9876-543210987654\",\n \"paymentProvider\": \"STRIPE\",\n \"returnUrl\": \"https://example.com/order/confirmation\",\n \"cancelUrl\": \"https://example.com/order/checkout\",\n \"setAsDefaultPaymentProfile\": false,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"orderId": "44567801-a504-4f09-8089-31ea78bc239b",
"paymentProvider": "STRIPE",
"status": "PENDING",
"hostedUrl": "https://payments.example.com/setup/69321a62-f1fe-461f-8761-a19ae6587bb2",
"metadata": {
"source": "mobile_app",
"campaign": "summer_2024"
},
"createdAt": "2024-09-29T10:00:00Z",
"updatedAt": "2024-09-29T10:30:00Z"
}{
"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
apiKeybearerAuth & apiKey
An API key that grants access to the Connect API. You can create and manage API keys in the portal.
Headers
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:
256Body
application/json
Request to create a new payment profile session for setting up a saved payment method.
The unique identifier of the order this payment profile session is associated with.
Example:
"9f8e7d6c-5b4a-3210-9876-543210987654"
Payment service provider that processes the transaction.
Available options:
STRIPE, BILLOGRAM Example:
"STRIPE"
The URL the customer is redirected to after the payment method is saved.
Example:
"https://example.com/order/confirmation"
The URL the customer is redirected to if they cancel before saving a payment method.
Example:
"https://example.com/order/checkout"
Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated. Defaults to false.
Example:
false
A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.
Show child attributes
Show child attributes
Response
Payment profile session created successfully
A payment profile session that wraps the process of setting up and saving a payment method for future use.
The unique identifier for this payment profile session.
Example:
"69321a62-f1fe-461f-8761-a19ae6587bb2"
The unique identifier of the order this payment profile session is associated with.
Example:
"44567801-a504-4f09-8089-31ea78bc239b"
Payment service provider that processes the transaction.
Available options:
STRIPE, BILLOGRAM Example:
"STRIPE"
Current status of a payment profile session lifecycle.
Available options:
PENDING, REQUIRES_ACTION, COMPLETED, FAILED, CANCELED Example:
"PENDING"
The hosted page to redirect the customer to in order to save their payment method.
Example:
"https://payments.example.com/setup/69321a62-f1fe-461f-8761-a19ae6587bb2"
Custom key-value pairs for additional payment profile session information.
Show child attributes
Show child attributes
Example:
{
"source": "mobile_app",
"campaign": "summer_2024"
}
When this payment profile session was created.
Example:
"2024-09-29T10:00:00Z"
When this payment profile session was last updated.
Example:
"2024-09-29T10:30:00Z"