Skip to main content
API docs by Redocly

Purse - Payment API (v2)

Download OpenAPI specification:Download

License: Purse

Process merchant transaction

authentication

OAuth2 client credentials authentication

OAuth2 client credentials authentication

Authorizations:
api_key
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

Responses

Response samples

Content type
application/json
{
  • "access_token": "2YotnFZFEjr1zCsicMWpAA",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

client-session

Resources used by the merchant front office to build a payment page and get authorization status.

Create a client session

Create a client session

Authorizations:
purse_oauth2
Request Body schema: application/json
required
entity_id
required
string <uuid>

ID of the entity that is using the orchestration API. This ID is provided by Purse.

amount
required
integer >= 0
Example: "4299"

Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR. Can only be set to 0 (zero) if /allow_future_usage is set to true.

currency
required
string (Currency)
Enum: "CHF" "EUR" "GBP" "JPY" "USD"
Example: "EUR"

ISO 4217 currency code

capture_mode
string (CaptureMode)
Default: "MANUAL"
Enum: "MANUAL" "AUTOMATIC" "PARTNER"
Example: "MANUAL"

Capture mode for the payment.

  • MANUAL - The merchant will manually capture the payment.
  • AUTOMATIC - The payment will be automatically captured.
  • PARTNER - The capture is delegated to the payment partner (PSP): the capture_delay is forwarded to the partner, which automatically captures the payment on its own once the delay has elapsed (Only available for Adyen).
capture_delay
string <duration> (CaptureDelay)
Example: "PT24H"

ISO-8601 duration to wait before the automatic capture is triggered. Only meaningful when capture_mode is AUTOMATIC or PARTNER.

integration_mode
string (IntegrationMode)
Default: "EMBEDDED"
Enum: "EMBEDDED" "HOSTED_PAGE"
Example: "HOSTED_PAGE"

Integration mode for the payment.

  • EMBEDDED - Widget will be setup by the merchant on its own page.
  • HOSTED_PAGE - Widget will be hosted and setup by Purse.
shopper_redirection_url
required
string <uri>
Example: "https://www.example.org/payment-callback?order_id=123456789"

URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET

required
object (Order)

Information regarding the order and the items to be purchased.

object (Customer)

Information regarding the customer purchasing the order.

object (PaymentThreeDsAuthenticationOptions)

Options for 3DS authentication.

object (Webhook)

If provided, merchant will receive webhook requests on the provided URL after each change in the client session status.

allow_future_usage
boolean

Default value is false. When true, this client session's authorization might be used in a future off session authorization, and /three_ds_authentication_options/challenge_indicator will be considered as CHALLENGE_REQUESTED_BY_MANDATE if not already provided.

object (AlreadyPaid)

Information about amounts already paid (e.g. deposits).

object (ClientSessionPartnerData)

Partner-specific data attached to a client session. Not persisted: only forwarded to the payment partner.

Responses

Request samples

Content type
application/json
{
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "amount": 12000,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "shopper_redirection_url": "https://example.org/redirect?order_id=123456789",
  • "customer": {
    },
  • "order": {
    },
  • "three_ds_authentication_options": {
    },
  • "webhook": {},
  • "allow_future_usage": false
}

Response samples

Content type
application/json
{
  • "id": "9753ec77-fc16-4886-92af-c7dcf9b7352d",
  • "status": "CREATED",
  • "amount": 12000,
  • "currency": "EUR",
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "capture_mode": "MANUAL",
  • "integration_mode": "EMBEDDED",
  • "allow_future_usage": false,
  • "order": {
    },
  • "expires_at": "2024-08-25T10:42:59.123+02:00",
  • "shopper_redirection_url": "https://example.org/redirect?order_id=123456789",
  • "widget": {},
  • "eligible_solutions": [
    ],
  • "links": {
    }
}

Get a client session by ID

Get a client session by ID

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1

Client session ID

Responses

Response samples

Content type
application/json
{
  • "id": "9753ec77-fc16-4886-92af-c7dcf9b7352d",
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "amount": 12000,
  • "currency": "EUR",
  • "shopper_redirection_url": "https://example.org/redirect?order_id=123456789",
  • "capture_mode": "MANUAL",
  • "integration_mode": "EMBEDDED",
  • "order": {
    },
  • "status": "SUBMITTED",
  • "expires_at": "2024-08-25T10:42:59.123+02:00",
  • "widget": {},
  • "payment_id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
  • "eligible_solutions": [
    ],
  • "links": {
    }
}

Abort a client session by ID

Abort a client session by ID

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1

ID of the client session to abort

Request Body schema: application/json
status
required
string
Enum: "ABORTED_BY_CUSTOMER" "ABORTED_BY_MERCHANT"

Responses

Request samples

Content type
application/json
{
  • "status": "ABORTED_BY_MERCHANT"
}

Response samples

Content type
application/json
{
  • "id": "9753ec77-fc16-4886-92af-c7dcf9b7352d",
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "amount": 12000,
  • "currency": "EUR",
  • "shopper_redirection_url": "https://example.org/redirect?order_id=123456789",
  • "capture_mode": "MANUAL",
  • "integration_mode": "EMBEDDED",
  • "status": "ABORTED_BY_MERCHANT",
  • "expires_at": "2024-08-25T10:42:59.123+02:00",
  • "order": {
    },
  • "widget": {},
  • "payment_id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
  • "eligible_solutions": [
    ],
  • "links": {
    }
}

payment

Payment management: capture, refund, void

Create a new payment

Create a new payment

Authorizations:
purse_oauth2api_key
header Parameters
x-idempotency-key
string
Example: CAP#1223445

Client-generated key that makes the operation safe to retry.

Send the same key when retrying a request whose response was lost (client timeout, network error, 5xx). The operation is then executed at most once: the first call is processed normally, and any replay carrying the same key is answered with 409 and a resource_id pointing at the resource the first call created. A replay that arrives while the first call is still in flight is held for a bounded number of attempts and then answered the same way; if the first call never completes at all, the replay errors rather than resolving, so a retry that keeps failing with 5xx should be resolved by reading the payment back rather than by replaying the key again.

One key per operation, never one key per payment. A payment can legitimately be captured, voided or refunded several times — for example two partial captures on the same authorization. Keys are scoped to the payment, so two operations that reuse the same key on the same payment are treated as a replay and the second one is refused with 409 instead of being executed. Derive the key from the operation itself (your own capture/refund identifier, or the payment id plus a sequence number), never from the payment or the order alone.

Within one operation the key must be stable and reused unchanged across every retry, including a retry hours or days later — never regenerated per HTTP attempt. A key regenerated per attempt provides no protection at all.

Strongly recommended for batch and retry-driven integrations. Without it, a retry sent after a lost response is indistinguishable from a new operation, and is rejected with 400 once the requested amount is no longer available on the payment.

Request Body schema: application/json
required
amount
required
integer
Example: "4299"

Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR

currency
required
string (Currency)
Enum: "CHF" "EUR" "GBP" "JPY" "USD"
Example: "EUR"

ISO 4217 currency code

entity_id
required
string <uuid>

ID of the entity that is using the orchestration API. This ID is provided by Purse.

shopper_redirection_url
string <uri>
Example: "https://www.example.org/payment-callback?order_id=123456789"

URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET

capture_mode
string (CaptureMode)
Default: "MANUAL"
Enum: "MANUAL" "AUTOMATIC" "PARTNER"
Example: "MANUAL"

Capture mode for the payment.

  • MANUAL - The merchant will manually capture the payment.
  • AUTOMATIC - The payment will be automatically captured.
  • PARTNER - The capture is delegated to the payment partner (PSP): the capture_delay is forwarded to the partner, which automatically captures the payment on its own once the delay has elapsed (Only available for Adyen).
capture_delay
string <duration> (CaptureDelay)
Example: "PT24H"

ISO-8601 duration to wait before the automatic capture is triggered. Only meaningful when capture_mode is AUTOMATIC or PARTNER.

required
object (Order)

Information regarding the order and the items to be purchased.

object (Customer)

Information regarding the customer purchasing the order.

object (Webhook)

If provided, merchant will receive webhook requests on the provided URL after each change in the client session status.

object (Browser)

Browser information which should be collected by the partner front component.

allow_future_usage
boolean

Default value is false. When true, this client session's authorization might be used in a future off session authorization, and /three_ds_authentication_options/challenge_indicator will be considered as CHALLENGE_REQUESTED_BY_MANDATE if not already provided.

Array of DuplicateAuthorizationCandidate (object) or (DuplicateForeignAuthorizationCandidate (DuplicateForeignAuthorizationCandidate (object) or DuplicateForeignAuthorizationCandidate (object))) or NewAuthorizationCandidate (object)

How payment was split over payment partners.

object (AlreadyPaid)

Information about amounts already paid (e.g. deposits).

Responses

Request samples

Content type
application/json
{
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "amount": 12000,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "order": {
    },
  • "customer": {
    },
  • "browser": {
    },
  • "split": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "9a14962c-bdcf-49d1-8673-e75dfb48013f",
  • "created_at": "2020-08-25T10:42:59.123+02:00",
  • "version": 7,
  • "entity_id": "89a237d0-20f9-438e-b46c-3993c46b7bbe",
  • "amount": 4299,
  • "currency": "EUR",
  • "allow_future_usage": false,
  • "client_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "order_reference": "order_01",
  • "order": {
    },
  • "capture_mode": "MANUAL",
  • "amounts": {
    },
  • "overview": {
    },
  • "browser": {
    },
  • "split": [
    ],
  • "authorization": {
    },
  • "captures": [
    ],
  • "voids": [ ],
  • "refunds": [ ],
  • "links": {
    }
}

Get a payment by ID

Get a payment by ID

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1

Payment ID

header Parameters
Cache-Control
string
Example: max-age=3600

if max-age directive is specified, the payment data won't be fetched from the partners

Responses

Response samples

Content type
application/json
{
  • "id": "9a14962c-bdcf-49d1-8673-e75dfb48013f",
  • "created_at": "2020-08-25T10:42:59.123+02:00",
  • "version": 7,
  • "entity_id": "89a237d0-20f9-438e-b46c-3993c46b7bbe",
  • "amount": 4299,
  • "currency": "EUR",
  • "allow_future_usage": false,
  • "client_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "order_reference": "order_01",
  • "order": {
    },
  • "capture_mode": "MANUAL",
  • "amounts": {
    },
  • "overview": {
    },
  • "browser": {
    },
  • "split": [
    ],
  • "authorization": {
    },
  • "captures": [
    ],
  • "voids": [ ],
  • "refunds": [ ],
  • "links": {
    }
}

Capture a payment

Capture a payment

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: e3a6516b-0ec4-4a5b-92b0-7bb9693e81c0
header Parameters
x-idempotency-key
string
Example: CAP#1223445

Client-generated key that makes the operation safe to retry.

Send the same key when retrying a request whose response was lost (client timeout, network error, 5xx). The operation is then executed at most once: the first call is processed normally, and any replay carrying the same key is answered with 409 and a resource_id pointing at the resource the first call created. A replay that arrives while the first call is still in flight is held for a bounded number of attempts and then answered the same way; if the first call never completes at all, the replay errors rather than resolving, so a retry that keeps failing with 5xx should be resolved by reading the payment back rather than by replaying the key again.

One key per operation, never one key per payment. A payment can legitimately be captured, voided or refunded several times — for example two partial captures on the same authorization. Keys are scoped to the payment, so two operations that reuse the same key on the same payment are treated as a replay and the second one is refused with 409 instead of being executed. Derive the key from the operation itself (your own capture/refund identifier, or the payment id plus a sequence number), never from the payment or the order alone.

Within one operation the key must be stable and reused unchanged across every retry, including a retry hours or days later — never regenerated per HTTP attempt. A key regenerated per attempt provides no protection at all.

Strongly recommended for batch and retry-driven integrations. Without it, a retry sent after a lost response is indistinguishable from a new operation, and is rejected with 400 once the requested amount is no longer available on the payment.

Request Body schema: application/json
required
One of
amount
required
integer > 0
Example: "10"

Amount to be processed for the called operation.

object (PaymentOperationOrder)

Information regarding the order and the items to be purchased. This object is only valued for payment operations.

merchant_reference
string
Example: "CAP#1223445"

Reference of the operation in the merchant system.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 10,
  • "order": {
    },
  • "merchant_reference": "CAP#1223445"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "overview": {
    },
  • "client_session_id": "083e320e-e2e2-4a94-b5e1-abc028b960ab",
  • "payment_link_id": "b299d88a-1d8a-4d54-8352-aa90479aab46",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 3,
  • "order_reference": "order_01",
  • "order": {
    },
  • "customer": {
    },
  • "amount": 4299,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "capture_delay": "PT24H",
  • "captures": [
    ],
  • "voids": [
    ],
  • "refunds": [
    ],
  • "authorization": {
    },
  • "authentication": {
    },
  • "amounts": {
    },
  • "links": {
    },
  • "browser": {
    },
  • "split": [
    ],
  • "webhook": {},
  • "allow_future_usage": true,
  • "already_paid": {
    },
  • "redirection": {}
}

Refund a payment

Refund a payment

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: e3a6516b-0ec4-4a5b-92b0-7bb9693e81c0
header Parameters
x-idempotency-key
string
Example: CAP#1223445

Client-generated key that makes the operation safe to retry.

Send the same key when retrying a request whose response was lost (client timeout, network error, 5xx). The operation is then executed at most once: the first call is processed normally, and any replay carrying the same key is answered with 409 and a resource_id pointing at the resource the first call created. A replay that arrives while the first call is still in flight is held for a bounded number of attempts and then answered the same way; if the first call never completes at all, the replay errors rather than resolving, so a retry that keeps failing with 5xx should be resolved by reading the payment back rather than by replaying the key again.

One key per operation, never one key per payment. A payment can legitimately be captured, voided or refunded several times — for example two partial captures on the same authorization. Keys are scoped to the payment, so two operations that reuse the same key on the same payment are treated as a replay and the second one is refused with 409 instead of being executed. Derive the key from the operation itself (your own capture/refund identifier, or the payment id plus a sequence number), never from the payment or the order alone.

Within one operation the key must be stable and reused unchanged across every retry, including a retry hours or days later — never regenerated per HTTP attempt. A key regenerated per attempt provides no protection at all.

Strongly recommended for batch and retry-driven integrations. Without it, a retry sent after a lost response is indistinguishable from a new operation, and is rejected with 400 once the requested amount is no longer available on the payment.

Request Body schema: application/json
One of
amount
required
integer > 0
Example: "10"

Amount to be processed for the called operation.

object (PaymentOperationOrder)

Information regarding the order and the items to be purchased. This object is only valued for payment operations.

merchant_reference
string
Example: "CAP#1223445"

Reference of the operation in the merchant system.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 10,
  • "order": {
    },
  • "merchant_reference": "CAP#1223445"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "overview": {
    },
  • "client_session_id": "083e320e-e2e2-4a94-b5e1-abc028b960ab",
  • "payment_link_id": "b299d88a-1d8a-4d54-8352-aa90479aab46",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 3,
  • "order_reference": "order_01",
  • "order": {
    },
  • "customer": {
    },
  • "amount": 4299,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "capture_delay": "PT24H",
  • "captures": [
    ],
  • "voids": [
    ],
  • "refunds": [
    ],
  • "authorization": {
    },
  • "authentication": {
    },
  • "amounts": {
    },
  • "links": {
    },
  • "browser": {
    },
  • "split": [
    ],
  • "webhook": {},
  • "allow_future_usage": true,
  • "already_paid": {
    },
  • "redirection": {}
}

Void a payment

Void a payment

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: e3a6516b-0ec4-4a5b-92b0-7bb9693e81c0
header Parameters
x-idempotency-key
string
Example: CAP#1223445

Client-generated key that makes the operation safe to retry.

Send the same key when retrying a request whose response was lost (client timeout, network error, 5xx). The operation is then executed at most once: the first call is processed normally, and any replay carrying the same key is answered with 409 and a resource_id pointing at the resource the first call created. A replay that arrives while the first call is still in flight is held for a bounded number of attempts and then answered the same way; if the first call never completes at all, the replay errors rather than resolving, so a retry that keeps failing with 5xx should be resolved by reading the payment back rather than by replaying the key again.

One key per operation, never one key per payment. A payment can legitimately be captured, voided or refunded several times — for example two partial captures on the same authorization. Keys are scoped to the payment, so two operations that reuse the same key on the same payment are treated as a replay and the second one is refused with 409 instead of being executed. Derive the key from the operation itself (your own capture/refund identifier, or the payment id plus a sequence number), never from the payment or the order alone.

Within one operation the key must be stable and reused unchanged across every retry, including a retry hours or days later — never regenerated per HTTP attempt. A key regenerated per attempt provides no protection at all.

Strongly recommended for batch and retry-driven integrations. Without it, a retry sent after a lost response is indistinguishable from a new operation, and is rejected with 400 once the requested amount is no longer available on the payment.

Request Body schema: application/json
One of
amount
required
integer > 0
Example: "10"

Amount to be processed for the called operation.

object (PaymentOperationOrder)

Information regarding the order and the items to be purchased. This object is only valued for payment operations.

merchant_reference
string
Example: "CAP#1223445"

Reference of the operation in the merchant system.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 10,
  • "order": {
    },
  • "merchant_reference": "CAP#1223445"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "overview": {
    },
  • "client_session_id": "083e320e-e2e2-4a94-b5e1-abc028b960ab",
  • "payment_link_id": "b299d88a-1d8a-4d54-8352-aa90479aab46",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 3,
  • "order_reference": "order_01",
  • "order": {
    },
  • "customer": {
    },
  • "amount": 4299,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "capture_delay": "PT24H",
  • "captures": [
    ],
  • "voids": [
    ],
  • "refunds": [
    ],
  • "authorization": {
    },
  • "authentication": {
    },
  • "amounts": {
    },
  • "links": {
    },
  • "browser": {
    },
  • "split": [
    ],
  • "webhook": {},
  • "allow_future_usage": true,
  • "already_paid": {
    },
  • "redirection": {}
}

Get a payment link by ID

Retrieve a payment link by its unique identifier

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>
Example: 7d9c5288-d7bb-423b-bff7-5c0727cb0adc

Payment link ID

Responses

Response samples

Content type
application/json
{
  • "id": "7d9c5288-d7bb-423b-bff7-5c0727cb0adc",
  • "version": 1,
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "status": "PAID",
  • "amount": 12000,
  • "currency": "EUR",
  • "shopper_redirection_url": "https://example.org/redirect?order_id=123456789",
  • "capture_mode": "MANUAL",
  • "expires_at": "2024-08-25T10:42:59.123+02:00",
  • "links": {},
  • "customer": {
    },
  • "order": {
    },
  • "allow_future_usage": false,
  • "payment_attempts": [
    ]
}

signing - jwks

Retrieve public signing keys (JWKS)

Retrieve public signing keys (JWKS)

Returns a list of public keys used to sign the purse-redirection-data tokens. These keys can be used to validate the integrity of the redirection token via JWS.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

eligible-solutions

Check eligible solution for a future payment.

A way to retrieve eligible modes of payment given a Order + Customer pair.

Authorizations:
purse_oauth2
Request Body schema: application/json
entity_id
required
string <uuid>

ID of the entity that is using the orchestration API. This ID is provided by Purse.

amount
required
integer >= 0
Example: "4299"

Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR. Can only be set to 0 (zero) if /allow_future_usage is set to true.

currency
required
string (Currency)
Enum: "CHF" "EUR" "GBP" "JPY" "USD"
Example: "EUR"

ISO 4217 currency code

required
object (Order)

Information regarding the order and the items to be purchased.

object (Customer)

Information regarding the customer purchasing the order.

allow_future_usage
boolean

Default value is false. When true, this order might be the first of several recurring payments.

Responses

Request samples

Content type
application/json
{
  • "entity_id": "5e3a0862-7cc3-4427-92ba-9e1e9595f571",
  • "amount": 12000,
  • "currency": "EUR",
  • "customer": {
    },
  • "order": {
    },
  • "allow_future_usage": false
}

Response samples

Content type
application/json
{
  • "amount": 4299,
  • "currency": "EUR",
  • "eligible_solutions": [
    ]
}