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

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.
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.
allow_future_usage
boolean
Default: false

When true, the payment associated to the client-session might be used to create future MIT. For creditcard payment /three_ds_authentication_options/challenge_indicator must be sent as CHALLENGE_REQUESTED_BY_MERCHANT

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.

Responses

Request samples

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

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"

The new status of the aborted client session.

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

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",
  • "version": 7,
  • "created_at": "2020-08-25T10:42:59.123+02:00",
  • "entity_id": "89a237d0-20f9-438e-b46c-3993c46b7bbe",
  • "amount": 4299,
  • "currency": "EUR",
  • "client_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "order_reference": "order_01",
  • "order": {
    },
  • "capture_mode": "MANUAL",
  • "amounts": {
    },
  • "overview": {
    },
  • "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 related to this operation. This object is only valued for payment operations and only required for some payment methods.

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",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 3,
  • "order_reference": "order_01",
  • "order": {
    },
  • "amount": 4299,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "allow_future_usage": true,
  • "captures": [
    ],
  • "voids": [
    ],
  • "refunds": [
    ],
  • "authorization": {
    },
  • "amounts": {
    },
  • "links": {
    },
  • "split": [
    ],
  • "webhook": {},
  • "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 related to this operation. This object is only valued for payment operations and only required for some payment methods.

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",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 3,
  • "order_reference": "order_01",
  • "order": {
    },
  • "amount": 4299,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "allow_future_usage": true,
  • "captures": [
    ],
  • "voids": [
    ],
  • "refunds": [
    ],
  • "authorization": {
    },
  • "amounts": {
    },
  • "links": {
    },
  • "split": [
    ],
  • "webhook": {},
  • "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 related to this operation. This object is only valued for payment operations and only required for some payment methods.

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",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 3,
  • "order_reference": "order_01",
  • "order": {
    },
  • "amount": 4299,
  • "currency": "EUR",
  • "capture_mode": "MANUAL",
  • "allow_future_usage": true,
  • "captures": [
    ],
  • "voids": [
    ],
  • "refunds": [
    ],
  • "authorization": {
    },
  • "amounts": {
    },
  • "links": {
    },
  • "split": [
    ],
  • "webhook": {},
  • "redirection": {}
}

Create a new payment

Create a new payment

Authorizations:
purse_oauth2
Request Body schema: application/json
required
amount
required
integer > 0
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.

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.
allow_future_usage
boolean

Default value is false. When true, this payment might be used to create future MIT, and /three_ds_authentication_options/challenge_indicator must be sent as CHALLENGE_REQUESTED_BY_MERCHANT

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.

Array of DuplicateAuthorizationCandidate (object) or (DuplicateForeignAuthorizationCandidate (DuplicateForeignAuthorizationCandidate (object) or DuplicateForeignAuthorizationCandidate (object))) or NewAuthorizationCandidate (object)
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

object (Browser)

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

Responses

Request samples

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

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": {
    },
  • "order_reference": "order_01",
  • "capture_mode": "MANUAL",
  • "amounts": {
    },
  • "overview": {
    },
  • "split": [
    ],
  • "authorization": {
    },
  • "captures": [
    ],
  • "voids": [ ],
  • "refunds": [ ],
  • "links": {
    }
}

Get a payment link by ID

Retrieve a payment link by its ID

Authorizations:
purse_oauth2
path Parameters
id
required
string <uuid>

Get payment-link by 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,
  • "payments": [
    ],
  • "client_sessions": [
    ]
}

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