Skip to main content
API docs by Redocly

Purse - Payment API (v1)

Download OpenAPI specification:Download

Payment API

Authentication

OAuth2 client credentials authentication

Authorizations:
BasicAuthApiKey
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
}

POS API

Endpoints used to process payment in a POS environement

Session API

Validates the selected payment solutions

Authorizations:
ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

session
required
string <uuid>

id of the session to validate

Request Body schema: application/json
required
Array
object (Order)
hook
string <url> (HookURL)
Example: "https://example.org/order/ORDER_ID/payment_hooks"

The URL on which updates will be sent to.

amount
number
Example: "10.99"

Amount to be processed for this specific request. This can be different than order amount.

partner
string
method
string
step_id
integer <int32>
Default: 0
Example: "0"

The ID of the init step which you want to validate. It is returned after each init call.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Initializes the payment solution

Authorizations:
ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

session
required
string <uuid>

id of the session to init

Request Body schema: application/json
required
object (Order)
hook
string <url> (HookURL)
Example: "https://example.org/order/ORDER_ID/payment_hooks"

The URL on which updates will be sent to.

amount
number
Example: "10.99"

Amount to be processed for this specific request. This can be different than order amount.

partner
string
method
string
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "hook": "https://example.org/order/ORDER_ID/payment_hooks",
  • "amount": 10.99,
  • "partner": "string",
  • "method": "string"
}

Creates a new session for an order

Authorizations:
OAuth2ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

Request Body schema: application/json
required
object (Order)
hook
string <url> (HookURL)
Example: "https://example.org/order/ORDER_ID/payment_hooks"

The URL on which updates will be sent to.

amount
number
Example: "10.99"

Amount to be processed for this specific request. This can be different than order amount.

information_request
boolean
Default: false
Example: "true"

Set to true if this is not a payment but just a card information request

recurring_payment
boolean
Default: false
Example: "true"

Set to true if this is a recurring payment

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "hook": "https://example.org/order/ORDER_ID/payment_hooks",
  • "amount": 10.99,
  • "information_request": true,
  • "recurring_payment": true
}

Transaction API

Initiates a transaction with an action on a payment solution

Authorizations:
OAuth2ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

action
required
string
Enum: "AUTHORIZE" "VOID" "CAPTURE" "REFUND" "OFF_SESSION_AUTHORIZE"
Request Body schema: application/json
required
object (Order)
hook
string <url> (HookURL)
Example: "https://example.org/order/ORDER_ID/payment_hooks"

The URL on which updates will be sent to.

amount
number
Example: "10.99"

Amount to be processed for this specific request. This can be different than order amount.

partner
string
method
string
step_id
integer <int32>
Default: 0
Example: "0"

The ID of the init step which you want to validate. It is returned after each init call.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "hook": "https://example.org/order/ORDER_ID/payment_hooks",
  • "amount": 10.99,
  • "partner": "string",
  • "method": "string",
  • "step_id": 0
}

Executes an action on a transaction

Authorizations:
OAuth2ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

action
required
string
Enum: "AUTHORIZE" "VOID" "CAPTURE" "REFUND" "OFF_SESSION_AUTHORIZE"
transaction
required
string <uuid>

For the CAPTURE, VOID and OFF_SESSION_AUTHORIZE actions, you will need the ID of the authorisation transaction to perform the call. For the REFUND action, you will need the ID of the CAPTURE ID transaction

header Parameters
x-idempotency-key
string

Unique identifier for the given request.

For instance, using a timestamp is strongly discouraged, while a unique identifier of the transaction on your end is advised.

Upon using this header, UpStream Pay action on transaction API will only execute the action once, and each subsequent call to the same endpoint with the same x-idempotency-key header value will return the first call’s result.

Note that this is only true for 14 days, so this does not replace a call to the get transactions for session API

Request Body schema: application/json
required
object (Order)
hook
string <url> (HookURL)
Example: "https://example.org/order/ORDER_ID/payment_hooks"

The URL on which updates will be sent to.

amount
number
Example: "10.99"

Amount to be processed for this specific request. This can be different than order amount.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "hook": "https://example.org/order/ORDER_ID/payment_hooks",
  • "amount": 10.99
}

Fetches the status of a single transaction

Authorizations:
OAuth2ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

transaction
required
string <uuid>

id of the transaction

Responses

Response samples

Content type
application/json
{
  • "method": "paypal",
  • "id": "4bd31c68-8cc8-4db1-982a-5e8e7bfd87c9",
  • "session_id": "dbaf74ee-e248-4f54-b622-15b054ed1fbc",
  • "entity_id": "fce21839-4469-aba7-b622-15b054ed1fbc",
  • "transaction_id": "fce21839-24bf-4469-aba7-074bab328a22",
  • "date": "2020-08-25T10:42:59+02:00",
  • "status": {
    },
  • "partner": "braintree",
  • "plugin_result": {
    }
}

Fetches the status of each transaction for a session

Authorizations:
OAuth2ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

session
required
string <uuid>

id of the session

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deprecated

Fetches the status of each transaction created for an order

WARNING ! NOT RECOMMENDED ! Orders are not unique Ids. There is a risk that you do not receive the proper data. It is advised to use the sessionId

Authorizations:
OAuth2ApiKey
path Parameters
entity
required
string <uuid>

id of the entity

order
required
string

id of the order (Careful, you must ensure the unicity of the order id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Pos API

Check a giftcard avaibility

path Parameters
entityId
required
string <uuid>

id of the entity

Request Body schema: application/json
required
method
string
Example: "softpos"

The method on which this result is associated.

partner
string
Example: "illicado"

The partner on which this result is associated.

amount
number
Example: "399.98"

The total amount of this item including vat.

object (PaymentDataPosResponse)

Request samples

Content type
application/json
{
  • "method": "softpos",
  • "partner": "illicado",
  • "amount": 399.98,
  • "payment_data": {
    }
}

Capture a payment in a POS environment

path Parameters
entityId
required
string <uuid>

id of the entity

Request Body schema: application/json
required
method
string
Example: "softpos"

The method on which this result is associated.

partner
string
Example: "illicado"

The partner on which this result is associated.

amount
number
Example: "399.98"

The total amount of this item including vat.

object (PaymentDataPosResponse)
object (OrderDataPos)

Request samples

Content type
application/json
{
  • "method": "softpos",
  • "partner": "illicado",
  • "amount": 399.98,
  • "payment_data": {
    },
  • "order": {
    }
}