--- title: Payment Profile Sessions description: Create sessions for setting up payment profiles. --- # Payment Profile Sessions Create sessions for setting up payment profiles. ## [POST /payment-profiles/sessions](/api-reference/payment-profile-sessions#tag/payment-profile-sessions/POST/payment-profiles/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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — 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. ### Request body (required) Type: `object` - `orderId` (`string`, required, example 9f8e7d6c-5b4a-3210-9876-543210987654) — The unique identifier of the order this payment profile session is associated with. - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `returnUrl` (`string`, required, example https://example.com/order/confirmation) — The URL the customer is redirected to after the payment method is saved. - `cancelUrl` (`string`, optional, example https://example.com/order/checkout) — The URL the customer is redirected to if they cancel before saving a payment method. - `setAsDefaultPaymentProfile` (`boolean`, optional, example false) — Whether to set the saved payment method as the customer's default for future payments. Defaults to false. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ### Responses #### 201 Payment profile session created successfully Type: [PaymentProfileSession](/api-reference/models.md#models/PaymentProfileSession) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/sessions \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "orderId": "9f8e7d6c-5b4a-3210-9876-543210987654", "paymentProvider": "STRIPE", "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout", "setAsDefaultPaymentProfile": false, "metadata": { "propertyName": "string" } }' ``` ## [GET /payment-profiles/sessions/{paymentProfileSessionId}](/api-reference/payment-profile-sessions#tag/payment-profile-sessions/GET/payment-profiles/sessions/{paymentProfileSessionId}) Get payment profile session Retrieve details of a specific payment profile session by its identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `paymentProfileSessionId` (`string`, required) — The unique identifier of the payment profile session to retrieve. ### Responses #### 200 Payment profile session retrieved successfully Type: [PaymentProfileSession](/api-reference/models.md#models/PaymentProfileSession) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/sessions/b4c5d6e7-f8a9-0123-4567-234567890123 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /payment-profiles/sessions/{paymentProfileSessionId}/cancel](/api-reference/payment-profile-sessions#tag/payment-profile-sessions/POST/payment-profiles/sessions/{paymentProfileSessionId}/cancel) Cancel payment profile session Cancel an active payment profile session, preventing further setup attempts. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `paymentProfileSessionId` (`string`, required) — The unique identifier of the payment profile session to cancel. ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — 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. ### Request body (optional) Type: `object` - `reason` (`string`, optional, example Customer decided not to save payment method) — Optional reason for cancelling the payment profile session. - `metadata` (`object with string keys`, optional, example {"cancelled_by":"customer_service","ticket_id":"SUPP-12345"}) — Custom key-value pairs for additional cancellation information. - `*` (`string`, optional) ### Responses #### 200 Payment profile session canceled successfully Type: [PaymentProfileSession](/api-reference/models.md#models/PaymentProfileSession) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/sessions/c5d6e7f8-a9b0-1234-5678-345678901234/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "reason": "Customer decided not to save payment method", "metadata": { "cancelled_by": "customer_service", "ticket_id": "SUPP-12345" } }' ```