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

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"
Example: "MANUAL"

Capture mode for the payment.

  • MANUAL - The merchant will manually capture the payment.
  • AUTOMATIC - The payment will be automatically captured.
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.

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).

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
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"
Example: "MANUAL"

Capture mode for the payment.

  • MANUAL - The merchant will manually capture the payment.
  • AUTOMATIC - The payment will be automatically captured.
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.

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
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
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
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": [
    ]
}