openapi: 3.0.3 info: title: Purse - Payment API description: Process merchant transaction version: v2 license: name: Purse url: https://purse.eu/fr/mentions-legales/ servers: - url: https://api.purse-sandbox.com/payment description: Payment server tags: - name: authentication description: OAuth2 client credentials authentication x-displayName: authentication - name: client-session description: >- Resources used by the merchant front office to build a payment page and get authorization status. x-displayName: client-session - name: payment description: 'Payment management: capture, refund, void' x-displayName: payment - name: payment-link description: Payment link x-displayName: payment-link - name: signing - jwks description: Retrieve public signing keys (JWKS) x-displayName: signing - jwks - name: eligible-solutions x-displayName: eligible-solutions paths: /oauth/token: servers: - url: https://api.purse-sandbox.com post: tags: - authentication summary: OAuth2 client credentials authentication operationId: clientCredentialsAuthentication requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type properties: grant_type: type: string enum: - client_credentials responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Oauth2TokenResponse' '400': description: Bad Request content: '*/*': schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: '*/*': schema: $ref: '#/components/schemas/ApiError' security: - api_key: [] /v2/signing-jwks: get: tags: - signing - jwks summary: Retrieve public signing keys (JWKS) description: > 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. operationId: getSigningJwks responses: '200': description: A list of public signing keys (JSON Web Key Set) content: application/json: schema: type: object properties: keys: type: array items: type: object properties: kty: type: string description: Key type (e.g. RSA) example: RSA e: type: string description: Public exponent (base64url encoded) example: AQAB kid: type: string description: Key ID (unique identifier) example: '12345' 'n': type: string description: Modulus (base64url encoded) example: 0vx7agoebGcQS...5I '400': description: Bad Request content: '*/*': schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: '*/*': schema: $ref: '#/components/schemas/ApiError' security: - api_key: [] /v2/eligible-solutions: post: tags: - eligible-solutions summary: Check eligible solution for a future payment. description: >- A way to retrieve eligible modes of payment given a Order + Customer pair. operationId: getEligibleSolutions requestBody: content: application/json: schema: $ref: '#/components/schemas/EligibleSolutionsCandidateApplication' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/EligibleSolutionsRepresentation' '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '503': description: Bad Gateway content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '504': description: Gateway timeout content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/client-sessions: post: tags: - client-session summary: Create a client session description: Create a client session operationId: createClientSession requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientSessionApplication' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/ClientSession' example: 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: reference: '123456789' additional_data: custom_field1: custom value custom_field2: 123 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true product_uri: https://www.example.org/product/1 image_uri: https://www.example.org/product/1.jpg - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 expires_at: '2024-08-25T10:42:59.123+02:00' shopper_redirection_url: https://example.org/redirect?order_id=123456789 widget: data: w9R5pLx2E7fqA3B1cV8z0YeL js_url: https://cdn.purse-secure.com/dropin/v3-stable/purse.js eligible_solutions: - partner: illicado method: giftcard - partner: dalenys method: creditcard - partner: paypal method: wallet - partner: oney method: cb3x links: self: href: /v2/client-sessions/9753ec77-fc16-4886-92af-c7dcf9b7352d method: GET '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '503': description: Bad Gateway content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '504': description: Gateway timeout content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/client-sessions/{id}: parameters: - name: id description: Client session ID in: path required: true schema: type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 get: tags: - client-session summary: Get a client session by ID description: Get a client session by ID operationId: getClientSessionById responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/ClientSession' example: 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: reference: '123456789' additional_data: custom_field1: custom value custom_field2: 123 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true product_uri: https://www.example.org/product/1 image_uri: https://www.example.org/product/1.jpg - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 status: SUBMITTED expires_at: '2024-08-25T10:42:59.123+02:00' widget: data: w9R5pLx2E7fqA3B1cV8z0YeL js_url: https://cdn.purse-secure.com/dropin/v3-stable/purse.js payment_id: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 eligible_solutions: - partner: illicado method: giftcard - partner: dalenys method: creditcard - partner: paypal method: wallet - partner: oney method: cb3x links: self: href: /v2/client-sessions/9753ec77-fc16-4886-92af-c7dcf9b7352d method: GET abort: href: >- /v2/client-sessions/9753ec77-fc16-4886-92af-c7dcf9b7352d/abort method: POST payment: href: /v2/payments/e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 method: GET '404': description: Not found '429': description: Too many requests while calling upstream content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/client-sessions/{id}/abort: post: tags: - client-session summary: Abort a client session by ID description: Abort a client session by ID operationId: abortClientSessionById parameters: - name: id description: ID of the client session to abort in: path required: true schema: type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 requestBody: content: application/json: schema: $ref: '#/components/schemas/AbortClientSessionApplication' example: status: ABORTED_BY_MERCHANT responses: '200': description: Operation was successful content: application/json: schema: $ref: '#/components/schemas/ClientSession' example: 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: reference: '123456789' additional_data: custom_field1: custom value custom_field2: 123 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true product_uri: https://www.example.org/product/1 image_uri: https://www.example.org/product/1.jpg - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 widget: data: w9R5pLx2E7fqA3B1cV8z0YeL js_url: https://cdn.purse-secure.com/dropin/v3-stable/purse.js payment_id: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 eligible_solutions: - partner: illicado method: giftcard - partner: dalenys method: creditcard - partner: paypal method: wallet - partner: oney method: cb3x links: self: href: /v2/client-sessions/9753ec77-fc16-4886-92af-c7dcf9b7352d method: GET '400': description: Client Session status incompatible with abort request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Client session Not Found '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payments: post: tags: - payment summary: Create a new payment description: Create a new payment operationId: createPayment parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentApplication' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Payment' example: 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: reference: '123456789' additional_data: custom_field1: custom value custom_field2: 123 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true product_uri: https://www.example.org/product/1 image_uri: https://www.example.org/product/1.jpg - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 capture_mode: MANUAL amounts: authorize_pending: 0 total_authorized: 4299 total_voided: 0 available_to_void: 1299 total_captured: 3000 available_to_capture: 1299 total_refunded: 0 available_to_refund: 3000 overview: consumed: PARTIALLY captured: PARTIALLY voided: NOT refunded: NOT browser: user_agent: >- Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0 referrer: https://your_shop.com/order?id=1234 accept_header: text/html color_depth: 32 java_enabled: true javascript_enabled: true locale: fra screen_height: 1200 screen_width: 1600 utc_time_zone: 60 split: - partner: easy2play method: giftcard amount: 2000 - partner: dalenys method: creditcard amount: 2299 authorization: status: AUTHORIZED partner_transactions: - id: 1a14962c-bdcf-49d1-8673-e75dfb48013f created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: AUTHORIZED amount: 2000 partner: easy2play method: giftcard partner_reference: 6898f79aa20af partner_status: '1' partner_status_description: Successful operation status_code: SUCCEEDED - id: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: AUTHORIZED amount: 2299 partner: dalenys method: creditcard card: bin: '513842' type: CARTE_BANCAIRE last_four_digits: '1234' holder_name: John Doe expiry_month: '01' expiry_year: '24' country_code: FR fingerprint: mG/7oNfgy7dPj8/jhP5Ynr9u1U= selected_network: VISA three_ds: eci: '01' version: 2.2.0 flow: CHALLENGE ds_transaction_id: f8a333e9-cdc2-45d1-b9e5-dba95e00fa95 acs_transaction_id: 29828842-14c9-46bc-838b-adda7460c305 partner_reference: A4232036332 partner_status: '0000' partner_status_description: Successful operation status_code: SUCCEEDED save_token: true token_saved: true captures: - id: 1a14962c-bdcf-49d1-8673-e75dfb48013f amount: 3000 created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' triggered_by: MERCHANT merchant_reference: CAP#1223445 status: SUCCESS partner_transactions: - id: 4a14962c-bdcf-49d1-8673-e75dfb48013f created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: SUCCESS amount: 2000 partner: easy2play method: giftcard partner_reference: 9898f79aa20rt partner_status: '1' partner_status_description: Successful operation status_code: SUCCEEDED - id: 28267b24-4def-4440-b7a4-5ee0f145c56d created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: SUCCESS amount: 1000 partner: dalenys method: creditcard partner_reference: C5232036332 partner_status: '0000' partner_status_description: Successful operation status_code: SUCCEEDED voids: [] refunds: [] links: self: href: /v2/payment/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET capture: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/captures method: POST refund: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/refunds method: POST void: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/voids method: POST '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not found '409': description: Conflict - Idempotency violation content: application/problem+json: schema: $ref: '#/components/schemas/PaymentIdempotencyProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '503': description: Bad Gateway content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api - api_key: [] /v2/payments/{id}: get: tags: - payment summary: Get a payment by ID description: Get a payment by ID operationId: getPaymentById parameters: - name: id description: Payment ID in: path required: true schema: type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 - name: Cache-Control description: >- if max-age directive is specified, the payment data won't be fetched from the partners in: header required: false schema: type: string example: max-age=3600 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Payment' example: 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: reference: '123456789' additional_data: custom_field1: custom value custom_field2: 123 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true product_uri: https://www.example.org/product/1 image_uri: https://www.example.org/product/1.jpg - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 capture_mode: MANUAL amounts: authorize_pending: 0 total_authorized: 4299 total_voided: 0 available_to_void: 1299 total_captured: 3000 available_to_capture: 1299 total_refunded: 0 available_to_refund: 3000 overview: consumed: PARTIALLY captured: PARTIALLY voided: NOT refunded: NOT browser: user_agent: >- Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0 referrer: https://your_shop.com/order?id=1234 accept_header: text/html color_depth: 32 java_enabled: true javascript_enabled: true locale: fra screen_height: 1200 screen_width: 1600 utc_time_zone: 60 split: - partner: easy2play method: giftcard amount: 2000 - partner: dalenys method: creditcard amount: 2299 authorization: status: AUTHORIZED partner_transactions: - id: 1a14962c-bdcf-49d1-8673-e75dfb48013f created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: AUTHORIZED amount: 2000 partner: easy2play method: giftcard partner_reference: 6898f79aa20af partner_status: '1' partner_status_description: Successful operation status_code: SUCCEEDED - id: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: AUTHORIZED amount: 2299 partner: dalenys method: creditcard card: bin: '513842' type: CARTE_BANCAIRE last_four_digits: '1234' holder_name: John Doe expiry_month: '01' expiry_year: '24' country_code: FR fingerprint: mG/7oNfgy7dPj8/jhP5Ynr9u1U= selected_network: VISA three_ds: eci: '01' version: 2.2.0 flow: CHALLENGE ds_transaction_id: f8a333e9-cdc2-45d1-b9e5-dba95e00fa95 acs_transaction_id: 29828842-14c9-46bc-838b-adda7460c305 partner_reference: A4232036332 partner_status: '0000' partner_status_description: Successful operation status_code: SUCCEEDED captures: - id: 1a14962c-bdcf-49d1-8673-e75dfb48013f amount: 3000 created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' triggered_by: MERCHANT merchant_reference: CAP#1223445 status: SUCCESS partner_transactions: - id: 4a14962c-bdcf-49d1-8673-e75dfb48013f created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: SUCCESS amount: 2000 partner: easy2play method: giftcard partner_reference: 9898f79aa20rt partner_status: '1' partner_status_description: Successful operation status_code: SUCCEEDED - id: 28267b24-4def-4440-b7a4-5ee0f145c56d created_at: '2020-08-25T10:42:59.123+02:00' updated_at: '2020-08-25T10:42:59.123+02:00' status: SUCCESS amount: 1000 partner: dalenys method: creditcard partner_reference: C5232036332 partner_status: '0000' partner_status_description: Successful operation status_code: SUCCEEDED voids: [] refunds: [] links: self: href: /v2/payment/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET capture: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/captures method: POST refund: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/refunds method: POST void: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/voids method: POST '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not found '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '503': description: Bad Gateway content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payments/{id}/captures: post: tags: - payment summary: Capture a payment description: Capture a payment operationId: capturePayment requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentOperationApplication' required: true parameters: - name: id in: path required: true schema: type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e81c0 - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Payment' headers: x-created-operation-id: description: ID of the created operation schema: type: string format: uuid example: 1a14962c-bdcf-49d1-8673-e75dfb48013f '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '409': description: Conflict - Idempotency violation content: application/problem+json: schema: $ref: '#/components/schemas/OperationIdempotencyProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payments/{id}/refunds: post: tags: - payment summary: Refund a payment description: Refund a payment operationId: refundPayment parameters: - name: id in: path required: true schema: type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e81c0 - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentOperationApplication' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Payment' headers: x-created-operation-id: description: ID of the created operation schema: type: string format: uuid example: 1a14962c-bdcf-49d1-8673-e75dfb48013f '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '409': description: Conflict - Idempotency violation content: application/problem+json: schema: $ref: '#/components/schemas/OperationIdempotencyProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payments/{id}/voids: post: tags: - payment summary: Void a payment description: Void a payment operationId: voidPayment parameters: - name: id in: path required: true schema: type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e81c0 - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentOperationApplication' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Payment' headers: x-created-operation-id: description: ID of the created operation schema: type: string format: uuid example: 1a14962c-bdcf-49d1-8673-e75dfb48013f '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '409': description: Conflict - Idempotency violation content: application/problem+json: schema: $ref: '#/components/schemas/OperationIdempotencyProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payment-links: post: tags: - payment-link summary: Create a payment link description: >- Create a new payment link that can be shared with customers to collect payments operationId: createPaymentLink requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentLinkApplication' example: entity_id: 5e3a0862-7cc3-4427-92ba-9e1e9595f571 expires_at: '2024-08-25T10:42:59.123+02:00' amount: 12000 currency: EUR capture_mode: MANUAL shopper_redirection_url: https://example.org/redirect?order_id=123456789 order: reference: order_123456 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: USER_DELIVERY delivery_quickness: REGULAR delivery_method_reference: DHL-EXPRESS estimated_delivery_date_time: '2024-08-27T15:00:00+02:00' shipping_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: PROD-001 name: Product name brand: Example Brand quantity: 1 unit_gross_price: 10000 net_amount: 12000 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true categories: - Electronics - Gadgets additional_data: custom_field1: custom value custom_field2: 123 marketplace_sellers: - name: Acme Corp reference: '#42-ACME' total_sales_count: 10000 total_sales_amount: 12000 registration_date_time: '2020-01-01T00:00:00+01:00' last_update_date_time: '2024-01-01T00:00:00+01:00' customer: reference: CUST-12345 type: PERSON email: jane.doe@example.com gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe birth_date: '1992-05-20' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2021-03-10T10:00:00+01:00' update_date_time: '2024-03-10T10:00:00+01:00' password_update_date_time: '2024-03-10T10:00:00+01:00' purchase_count_last_day: 1 purchase_count_last_six_months: 8 purchase_count_last_year: 20 different_card_count_last_day: 1 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2024-08-20T10:00:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS purchase_total_amount: 50000 first_purchase_date_time: '2021-03-10T10:00:00+01:00' prior_purchase_date_time: '2024-07-20T10:00:00+02:00' three_ds_authentication_options: challenge_indicator: NO_CHALLENGE_REQUESTED challenge_exemption: LOW_VALUE webhook: url: https://www.example.org/payment-hook headers: - name: x-order-id values: - '123456789' - name: x-api-key values: - 9bbce5d2-501c-4fba-9442-3181efd2a7a3 allow_future_usage: false responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PaymentLink' example: id: 7d9c5288-d7bb-423b-bff7-5c0727cb0adc version: 1 entity_id: 5e3a0862-7cc3-4427-92ba-9e1e9595f571 status: CREATED 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: self: href: >- https://api.purse-dev.com/payment/v2/payment-links/7d9c5288-d7bb-423b-bff7-5c0727cb0adc method: GET customer_url: href: >- https://pay.purse-dev.com/payment-link/7d9c5288-d7bb-423b-bff7-5c0727cb0adc method: GET cancel: href: >- https://api.purse-dev.com/payment/v2/payment-links/7d9c5288-d7bb-423b-bff7-5c0727cb0adc/cancel method: POST customer: reference: CUST-12345 type: PERSON email: jane.doe@example.com gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe birth_date: '1992-05-20' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2021-03-10T10:00:00+01:00' update_date_time: '2024-03-10T10:00:00+01:00' password_update_date_time: '2024-03-10T10:00:00+01:00' purchase_count_last_day: 1 purchase_count_last_six_months: 8 purchase_count_last_year: 20 different_card_count_last_day: 1 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2024-08-20T10:00:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS purchase_total_amount: 50000 first_purchase_date_time: '2021-03-10T10:00:00+01:00' prior_purchase_date_time: '2024-07-20T10:00:00+02:00' order: reference: order_123456 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: USER_DELIVERY delivery_quickness: REGULAR delivery_method_reference: DHL-EXPRESS estimated_delivery_date_time: '2024-08-27T15:00:00+02:00' shipping_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: PROD-001 name: Product name brand: Example Brand quantity: 1 unit_gross_price: 10000 net_amount: 12000 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true categories: - Electronics - Gadgets additional_data: custom_field1: custom value custom_field2: 123 marketplace_sellers: - name: Acme Corp reference: '#42-ACME' total_sales_count: 10000 total_sales_amount: 12000 registration_date_time: '2020-01-01T00:00:00+01:00' last_update_date_time: '2024-01-01T00:00:00+01:00' allow_future_usage: false payment_attempts: [] '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '503': description: Bad Gateway content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payment-links/{id}: parameters: - name: id description: Payment link ID in: path required: true schema: type: string format: uuid example: 7d9c5288-d7bb-423b-bff7-5c0727cb0adc get: tags: - payment-link summary: Get a payment link by ID description: Retrieve a payment link by its unique identifier operationId: getPaymentLinkById responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PaymentLink' example: 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: self: href: >- https://api.purse-dev.com/payment/v2/payment-links/7d9c5288-d7bb-423b-bff7-5c0727cb0adc method: GET customer_url: href: >- https://pay.purse-dev.com/payment-link/7d9c5288-d7bb-423b-bff7-5c0727cb0adc method: GET cancel: href: >- https://api.purse-dev.com/payment/v2/payment-links/7d9c5288-d7bb-423b-bff7-5c0727cb0adc/cancel method: POST customer: reference: CUST-12345 type: PERSON email: jane.doe@example.com gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe birth_date: '1992-05-20' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2021-03-10T10:00:00+01:00' update_date_time: '2024-03-10T10:00:00+01:00' password_update_date_time: '2024-03-10T10:00:00+01:00' purchase_count_last_day: 1 purchase_count_last_six_months: 8 purchase_count_last_year: 20 different_card_count_last_day: 1 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2024-08-20T10:00:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS purchase_total_amount: 50000 first_purchase_date_time: '2021-03-10T10:00:00+01:00' prior_purchase_date_time: '2024-07-20T10:00:00+02:00' order: reference: order_123456 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: USER_DELIVERY delivery_quickness: REGULAR delivery_method_reference: DHL-EXPRESS estimated_delivery_date_time: '2024-08-27T15:00:00+02:00' shipping_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: PROD-001 name: Product name brand: Example Brand quantity: 1 unit_gross_price: 10000 net_amount: 12000 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true categories: - Electronics - Gadgets additional_data: custom_field1: custom value custom_field2: 123 marketplace_sellers: - name: Acme Corp reference: '#42-ACME' total_sales_count: 10000 total_sales_amount: 12000 registration_date_time: '2020-01-01T00:00:00+01:00' last_update_date_time: '2024-01-01T00:00:00+01:00' allow_future_usage: false payment_attempts: - payment_id: 05c0d03f-2404-48c5-a521-bd5a57d3b355 authorization_status: AUTHORIZED client_session_id: 05c0d03f-2404-48c5-a521-bd5a57d3b355 client_session_status: SUBMITTED '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '503': description: Bad Gateway content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api /v2/payment-links/{id}/cancel: post: tags: - payment-link summary: Cancel a payment link description: >- Cancel an active payment link. Once cancelled, the link can no longer be used for payments. operationId: cancelPaymentLink parameters: - name: id description: Payment link ID in: path required: true schema: type: string format: uuid example: 7d9c5288-d7bb-423b-bff7-5c0727cb0adc responses: '200': description: Operation was successful content: application/json: schema: $ref: '#/components/schemas/PaymentLink' example: id: 7d9c5288-d7bb-423b-bff7-5c0727cb0adc version: 1 entity_id: 5e3a0862-7cc3-4427-92ba-9e1e9595f571 status: CANCELLED 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: self: href: >- https://api.purse-dev.com/payment/v2/payment-links/7d9c5288-d7bb-423b-bff7-5c0727cb0adc method: GET customer_url: href: >- https://pay.purse-dev.com/payment-link/7d9c5288-d7bb-423b-bff7-5c0727cb0adc method: GET cancel: href: >- https://api.purse-dev.com/payment/v2/payment-links/7d9c5288-d7bb-423b-bff7-5c0727cb0adc/cancel method: POST customer: reference: CUST-12345 type: PERSON email: jane.doe@example.com gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe birth_date: '1992-05-20' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2021-03-10T10:00:00+01:00' update_date_time: '2024-03-10T10:00:00+01:00' password_update_date_time: '2024-03-10T10:00:00+01:00' purchase_count_last_day: 1 purchase_count_last_six_months: 8 purchase_count_last_year: 20 different_card_count_last_day: 1 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2024-08-20T10:00:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS purchase_total_amount: 50000 first_purchase_date_time: '2021-03-10T10:00:00+01:00' prior_purchase_date_time: '2024-07-20T10:00:00+02:00' order: reference: order_123456 net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: USER_DELIVERY delivery_quickness: REGULAR delivery_method_reference: DHL-EXPRESS estimated_delivery_date_time: '2024-08-27T15:00:00+02:00' shipping_address: gender: FEMALE first_name: Jane middle_name: Marie last_name: Doe address_lines: - 123 Main Street - Apartment 4B city: Paris postal_code: '75001' country_code: FR province_code: FR-IDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: PROD-001 name: Product name brand: Example Brand quantity: 1 unit_gross_price: 10000 net_amount: 12000 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true categories: - Electronics - Gadgets additional_data: custom_field1: custom value custom_field2: 123 marketplace_sellers: - name: Acme Corp reference: '#42-ACME' total_sales_count: 10000 total_sales_amount: 12000 registration_date_time: '2020-01-01T00:00:00+01:00' last_update_date_time: '2024-01-01T00:00:00+01:00' allow_future_usage: false payment_attempts: [] '400': description: Bad request - Payment link status incompatible with cancel request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Payment link not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - purse_oauth2: - payment-api components: parameters: IdempotencyKey: name: x-idempotency-key in: header required: false description: > 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. schema: type: string example: CAP#1223445 securitySchemes: purse_oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.purse-live.com/oauth2/token scopes: payment-api: use payment-api api_key: type: apiKey name: api_key in: header schemas: Oauth2TokenResponse: description: OAuth2 Response for the request of a Bearer Token type: object properties: access_token: description: Access Token to be used in accessing protected endpoints type: string expires_in: description: The lifetime in seconds of the Access Token type: integer scope: description: The scope of the Access Token type: string token_type: description: The type of the Token issued type: string required: - access_token - expires_in - token_type example: access_token: 2YotnFZFEjr1zCsicMWpAA token_type: Bearer expires_in: 3600 ApiError: type: object properties: timestamp: type: string description: The moment at which the error happened. format: date-time error_code: type: string description: The error code to interpret. example: AUTHORIZE_NOT_ALLOWED enum: - FORBIDDEN - INTERNAL_SERVER_ERROR - BAD_REQUEST - PAYLOAD_TOO_LARGE - NOT_IMPLEMENTED - NOT_FOUND - ALREADY_EXISTS - NO_SUCH_EXPERIENCE - EXPERIENCE_NOT_ELIGIBLE - UNAUTHORIZED_OUTGOING_CALL - AUTHORIZE_NOT_ALLOWED - PLUGIN_UNHANDLED_ERROR - PLUGIN_WORKFLOW_ERROR - PLUGIN_INPUT_ERROR - CREATE_ROOT_ENTITY_ERROR - ENTITY_SHOULD_HAVE_NAME_ERROR - ENTITY_SHOULD_HAVE_PARENT_ERROR - ENTITY_NOT_FOUND_ERROR - TRANSACTION_NOT_FOUND_ERROR - SESSION_ALREADY_SUBMITTED_ERROR - CREDIT_ALREADY_COMMITTED_ERROR - CREDIT_NOT_COMMITTED message: type: string description: The message explaining the cause of the error. example: >- Authorize action not callable, it can only be impersonated through status or verify action. request_id: type: string description: The unique ID of this request for debug purposes. example: '21987985' status: type: integer description: The HTTP status returned by this HTTP response. format: int32 example: 409 path: type: string error: type: string Currency: type: string description: ISO 4217 currency code enum: - CHF - EUR - GBP - JPY - USD example: EUR Address: type: object properties: company_name: type: string example: Company name gender: type: string enum: - MALE - FEMALE - UNKNOWN first_name: type: string example: Miles middle_name: type: string example: Eva last_name: type: string example: Morales address_lines: type: array items: type: string example: 1st Street maxItems: 5 city: type: string example: New York postal_code: type: string example: '10001' country_code: type: string example: US description: ISO 3166-1 alpha-2 country code province_code: type: string example: NY description: ISO 3166-2 country subdivision code phone_number: type: string example: '+526645951538' format: EP-164 description: > The customer's phone number at this address. The phone number must be in the E.164 format, for example, +526645951538. mobile_phone_number: type: string example: '+526645951538' format: EP-164 description: > The customer's mobile phone number at this address. The phone number must be in the E.164 format, for example, +526645951538. work_phone_number: type: string example: '+526645951538' format: EP-164 description: > The customer's work phone number at this address. The phone number must be in the E.164 format, for example, +526645951538. AccommodationDetails: type: object description: details regarding the booked accommodation properties: booking_reference: description: Unique reference number associated with the booking type: string name: description: Name of the accommodation facility or property type: string address: description: Physical address and contact details of the accommodation allOf: - $ref: '#/components/schemas/Address' category: description: Star rating or category classification of the property type: string check_in_date: description: Scheduled date (ISO 8601 format) of arrival or check-in type: string format: date example: '2025-08-25' check_out_date: description: Scheduled date (ISO 8601 format) of departure or check-out type: string format: date example: '2025-08-26' number_of_nights: description: Total number of nights for the stay type: integer minimum: 1 number_of_rooms: description: Number of rooms included in the booking type: integer minimum: 1 room_type: description: Type or classification of the room (e.g., Double, Single) type: string guests: description: Detailed breakdown of the guests included in the booking type: object properties: adult_count: description: Total number of adult guests type: integer minimum: 0 child_count: description: Total number of child guests type: integer minimum: 0 infant_count: description: Total number of infant guests type: integer minimum: 0 pet_count: description: Total number of pets included in the booking type: integer minimum: 0 ItemLine: type: object description: Information regarding the item. properties: type: type: string description: Type of item example: PHYSICAL enum: - PHYSICAL - DIGITAL - SHIPPING_FEES - TRAVEL_AND_TOURISM - TAXES - INSURANCE sku_reference: type: string description: Reference of the item for the merchant system example: SKU_01 name: type: string description: Name of the item example: My awesome product brand: type: string description: Brand of the item example: My awesome brand unit_gross_price: type: integer description: | Gross price of the item in currency minor unit. Unit price excluding taxes and discounts. example: 1099 net_amount: type: integer description: > Net amount of the item line in currency minor unit. Including taxes and discounts. Should respect the formula: `net_amount = (unit_gross_price * quantity) + tax_amount - discount_amount` example: 4299 discount_amount: type: integer description: | Discount amount of the item line in currency minor unit example: 0 deprecated: true quantity: type: integer description: Quantity of the item example: 4 tax_amount: type: integer description: Tax amount of the item line in currency minor unit. example: 399 tax_rate: type: number description: Tax rate of the item line. example: 20 seller_reference: type: string description: Reference of the seller for the merchant system example: SELLER_01 seller_name: type: string description: Name of the seller example: My awesome seller is_marketplace_seller: type: boolean description: Is the item sold by a marketplace seller example: true product_uri: type: string description: The product URL associated with the item format: uri example: https://www.example.org/product/1 image_uri: type: string description: The image URL associated with the item format: uri example: https://www.example.org/product/1.jpg categories: type: array description: List of all categories for the item. items: type: string example: 'Ex: ["Car", "Bicycle"]' accommodation_data: type: array description: Array containing specific details regarding the booked accommodation items: $ref: '#/components/schemas/AccommodationDetails' Shipment: type: object description: Information regarding shipping / delivery and the items to be shipped. properties: net_amount: type: integer description: Total amount of the shipment in currency minor unit. example: 4299 delivery_type: type: string description: Type of shipment example: USER_DELIVERY enum: - USER_DELIVERY - STORE_PICKUP - EXTERNAL_PICKUP - SHELF_PICKUP - DIGITAL_DELIVERY - BOOKING delivery_quickness: type: string description: Quickness of the shipment example: EXPRESS enum: - IMMEDIATE - EXPRESS - SAME_DAY - REGULAR delivery_method_reference: type: string description: Reference of the delivery method for the merchant system example: DHL estimated_delivery_date_time: type: string description: Estimated delivery date format: date-time example: '2020-08-25T10:42:59+02:00' shipping_address: type: object properties: company_name: type: string example: ACME gender: type: string enum: - MALE - FEMALE - UNKNOWN first_name: type: string example: Emily middle_name: type: string example: Rose last_name: type: string example: Parker address_lines: type: array items: type: string example: 1st Street maxItems: 5 city: type: string example: New York postal_code: type: string example: '10001' country_code: type: string example: US description: ISO 3166-1 alpha-2 country code province_code: type: string example: NY description: ISO 3166-2 country subdivision code phone_number: type: string example: '+526645951538' format: EP-164 description: > The customer's phone number at this address. The phone number must be in the E.164 format, for example, +526645951538. mobile_phone_number: type: string example: '+526645951538' format: EP-164 description: > The customer's mobile phone number at this address. The phone number must be in the E.164 format, for example, +526645951538. work_phone_number: type: string example: '+526645951538' format: EP-164 description: > The customer's work phone number at this address. The phone number must be in the E.164 format, for example, +526645951538. delivery_point_name: type: string description: Name of the delivery point example: Le Trop Quai. item_lines: type: array description: List of all items for the shipment. items: $ref: '#/components/schemas/ItemLine' Discount: type: object required: - net_amount - tax_amount properties: net_amount: type: integer description: Amount of the discount in currency minor unit. example: 0 tax_amount: type: integer description: Tax amount of the discount in currency minor unit. example: 0 coupon_code: type: string description: Coupon code used during the order. example: BLACK_FRIDAY seller_reference: type: string description: Reference of the seller for the merchant system example: SELLER_01 MarketplaceSeller: type: object properties: name: type: string example: Acme Corp reference: type: string example: '#42-ACME' description: Reference of the marketplace seller registration_date_time: type: string format: date-time example: '2020-01-01T00:00:00+01:00' description: Registration date of the marketplace seller last_update_date_time: type: string format: date-time example: '2020-01-01T00:00:00+01:00' description: Last update date of the marketplace seller total_sales_count: type: integer example: 10000 description: Total sales count of the marketplace seller minimum: 0 total_sales_amount: type: integer example: 12000 description: Total sales amount of the marketplace seller minimum: 0 Order: type: object description: Information regarding the order and the items to be purchased. required: - reference properties: reference: type: string example: order_01 description: >- Reference used to identify the order in the merchant system. Whenever possible, this reference will be propagated to the payment partners. net_amount: type: integer minimum: 1 description: >- Total amount of the order in currency minor unit. Including taxes and discounts. Order amount must be greater or equal than payment amount. example: 4299 discount_amount: type: integer minimum: 0 description: >- Discount amount of the order in currency minor unit. If discounts are provided at item_line level, this amount must be equal to the sum of all item_line discount_amount. example: 500 deprecated: true tax_amount: type: integer minimum: 0 description: >- Tax amount of the order in currency minor unit. If taxes are provided at item_line level, this amount must be equal to the sum of all item_line tax_amount. example: 3582 shipments: type: array description: List of all shipments for the order. items: $ref: '#/components/schemas/Shipment' billing_address: $ref: '#/components/schemas/Address' discounts: type: array items: $ref: '#/components/schemas/Discount' additional_data: type: object description: Additional data for the order as key-value pairs marketplace_sellers: type: array items: $ref: '#/components/schemas/MarketplaceSeller' Account: type: object description: >- Additional information of customer (account, history with the merchant...). properties: creation_date_time: type: string description: >- The date and time (ISO 8601 format) when the customer account has been created. format: date-time example: '2020-08-25T10:42:59+02:00' update_date_time: type: string description: >- The last date and time (ISO 8601 format) when the customer account has been last updated. format: date-time example: '2020-08-25T10:42:59+02:00' password_update_date_time: type: string description: >- The last date and time (ISO 8601 format) when the customer account password has been last updated. format: date-time example: '2020-08-25T10:42:59+02:00' purchase_count_last_day: type: integer description: >- Number of purchase transaction (successful and abandoned) for this account account during the last 24 hours. example: 3 purchase_count_last_six_months: type: integer description: Number of purchases for the account for the last six months. example: 5 purchase_count_last_year: type: integer description: >- Number of purchase transaction (successful and abandoned) for this account account during the last 12 months. example: 15 different_card_count_last_day: type: integer description: >- Number of different card attempt for the account during the last 24 hours. example: 3 authentication_method: type: string description: >- Information about how the account has been authenticated before the payment (for the current order). example: GUEST enum: - GUEST - MERCHANT_CREDENTIALS - IDENTITY_FEDERATION_CREDENTIALS - ISSUER_CREDENTIALS - THIRD_PARTY_CREDENTIALS - FIDO_CREDENTIALS authentication_date_time: type: string description: >- Date and time (ISO 8601 format) when the customer account has been authenticated in merchant system. format: date-time example: '2020-08-25T10:42:59+02:00' age_indicator: type: string description: Age of the account in the merchant system. example: MORE_60_DAYS enum: - GUEST - NEW - LESS_30_DAYS - BETWEEN_30_60_DAYS - MORE_60_DAYS change_indicator: type: string description: Age since the last update of the account in the merchant system example: MORE_60_DAYS enum: - NEW - LESS_30_DAYS - BETWEEN_30_60_DAYS - MORE_60_DAYS password_change_indicator: type: string description: >- Age since the last update of the password account in the merchant system. example: MORE_60_DAYS enum: - GUEST - NEW - LESS_30_DAYS - BETWEEN_30_60_DAYS - MORE_60_DAYS trust_indicator: type: string description: Customer's trustworthy level indicator. example: GOOD enum: - VERY_GOOD - GOOD - NEUTRAL - BAD - VERY_BAD purchase_total_amount: type: integer description: >- Total amount of all purchases made by the customer in currency minor unit. example: 125000 minimum: 0 first_purchase_date_time: type: string description: >- Date and time (ISO 8601 format) of the first purchase made by the customer. format: date-time example: '2020-08-25T10:42:59+02:00' prior_purchase_date_time: type: string description: >- Date and time (ISO 8601 format) of the last purchase made by the customer. format: date-time example: '2025-08-25T10:42:59+02:00' Customer: type: object description: Information regarding the customer purchasing the order. properties: reference: type: string example: customer_01 description: >- This reference will be used to identify the customer in the merchant system. email: type: string format: email example: eva.morales@example.org type: type: string enum: - PERSON - COMPANY example: PERSON company_identifier: type: string description: National company identification number (country specific). example: '12345678900012' company_name: type: string example: Company name gender: type: string enum: - MALE - FEMALE - UNKNOWN first_name: type: string example: Miles middle_name: type: string example: Eva last_name: type: string example: Morales national_identifier: type: string description: National identification number of the customer (country specific). example: MX-1234567890 birth_date: type: string format: date example: '1980-01-01' ip_address: type: string example: 45.15.207.98 description: Customer IP address, V4 or V6 locale: type: string example: en-US description: Customer locale, BCP 47 account: $ref: '#/components/schemas/Account' EligibleSolutionsCandidateApplication: description: Order / Customer pair to check all eligible mode of payment solutions. type: object required: - entity_id - amount - currency - order properties: entity_id: type: string format: uuid description: | ID of the entity that is using the orchestration API. This ID is provided by Purse. amount: type: integer example: 4299 minimum: 0 description: > 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: $ref: '#/components/schemas/Currency' order: $ref: '#/components/schemas/Order' customer: $ref: '#/components/schemas/Customer' allow_future_usage: type: boolean description: > Default value is `false`. When `true`, this order might be the first of several recurring payments. example: entity_id: 5e3a0862-7cc3-4427-92ba-9e1e9595f571 amount: 12000 currency: EUR customer: reference: '2090000000000' type: PERSON email: emily.rose.parker@example.org gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER birth_date: '1995-08-25' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2017-06-15T15:30:00+02:00' update_date_time: '2023-02-20T20:54:00+01:00' password_update_date_time: '2023-02-20T20:54:00+01:00' purchase_count_last_day: 0 purchase_count_last_six_months: 3 purchase_count_last_year: 8 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2023-10-30T15:33:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS purchase_total_amount: 12000 first_purchase_date_time: '2023-10-30T15:33:00+02:00' prior_purchase_date_time: '2024-12-30T15:33:00+02:00' order: reference: '123456789' net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true categories: - Clothing - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 categories: - Shipping marketplace_sellers: - name: Acme Corp reference: '#69-ACME' total_sales_count: 10000 total_sales_amount: 12000 registration_date_time: '2020-01-01T00:00:00+01:00' last_update_date_time: '2025-01-01T00:00:00+01:00' allow_future_usage: false EligibleSolutionDetails: description: details about the eligible solutions type: object properties: partner: description: the partner ilvolved in the solution type: string method: description: the method of payment of this solution type: string required: - partner - method EligibleSolutionsRepresentation: description: Eligible solutions to present to customer to pay the order. type: object properties: amount: type: integer example: 4299 minimum: 0 description: | Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR. currency: $ref: '#/components/schemas/Currency' eligible_solutions: type: array items: $ref: '#/components/schemas/EligibleSolutionDetails' required: - amount - currency - eligible_solutions ProblemDetail: title: An RFC 7807 problem object type: object properties: type: type: string format: uri-reference description: A URI reference that identifies the problem type. title: type: string description: A short, human-readable summary of the problem type. status: type: integer description: > The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 100 maximum: 599 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem. instance: type: string format: uri-reference description: > A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. error: description: Single error detail errors: type: array description: Error details items: type: object properties: detail: type: string description: Error detail pointer: type: string description: JSON Pointer for the field CaptureMode: type: string enum: - MANUAL - AUTOMATIC - PARTNER default: MANUAL example: MANUAL description: > 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). CaptureDelay: type: string format: duration example: PT24H description: | ISO-8601 duration to wait before the automatic capture is triggered. Only meaningful when `capture_mode` is `AUTOMATIC` or `PARTNER`. IntegrationMode: type: string enum: - EMBEDDED - HOSTED_PAGE default: EMBEDDED example: HOSTED_PAGE description: | 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. PaymentThreeDsAuthenticationOptions: type: object description: Options for 3DS authentication. properties: challenge_indicator: type: string enum: - NO_PREFERENCE - NO_CHALLENGE_REQUESTED - CHALLENGE_REQUESTED_BY_MERCHANT - CHALLENGE_REQUESTED_BY_MANDATE - NO_CHALLENGE_REQUESTED_RISK_ANALYSIS_ALREADY_PERFORMED - NO_CHALLENGE_REQUESTED_DATA_SHARE_ONLY - NO_CHALLENGE_REQUESTED_STRONG_AUTHENTICATION_ALREADY_PERFORMED - NO_CHALLENGE_REQUESTED_BY_TRUST_LIST - CHALLENGE_REQUESTED_BY_TRUST_LIST example: NO_PREFERENCE challenge_exemption: type: string enum: - TRANSACTION_RISK_ANALYSIS - TRUSTED_BENEFICIARY - LOW_VALUE - SECURE_CORPORATE example: LOW_VALUE Webhook: type: object description: >- If provided, merchant will receive webhook requests on the provided URL after each change in the client session status. required: - url properties: url: type: string format: uri example: https://www.example.org/payment-hook?order_id=123456789 description: URL to which webhooks will be sent via a POST request. headers: type: array description: Optional headers to be sent with the webhook request. items: type: object required: - name - values properties: name: type: string example: x-order-id values: type: array minItems: 1 items: type: string example: '123456789' event_types: type: array description: >- The types of webhook to subscribe to. If null or missing, default value is `["PAYMENT"]`. example: - PAYMENT_CAPTURE - PAYMENT_REFUND - PAYMENT_VOID items: type: string enum: - PAYMENT - PAYMENT_AUTHORIZATION - PAYMENT_AUTHORIZATION_PARTNER_TRANSACTION - PAYMENT_AUTHENTICATION - PAYMENT_AUTHENTICATION_PARTNER_AUTHENTICATION - PAYMENT_CAPTURE - PAYMENT_CAPTURE_PARTNER_TRANSACTION - PAYMENT_REFUND - PAYMENT_REFUND_PARTNER_TRANSACTION - PAYMENT_VOID - PAYMENT_VOID_PARTNER_TRANSACTION - PAYMENT_LINK AlreadyPaidDetail: type: object description: Detail of an already paid amount. required: - net_amount properties: type: type: string enum: - DEPOSIT - EXTERNAL description: Type of the already paid amount. example: DEPOSIT name: type: string description: Display name for the already paid amount. example: Acompte net_amount: type: integer description: Already paid detail amount in currency minor unit. example: 10000 minimum: 0 AlreadyPaid: type: object description: Information about amounts already paid (e.g. deposits). required: - net_amount properties: net_amount: type: integer description: Total already paid amount in currency minor unit. example: 20000 minimum: 0 details: type: array description: Breakdown of already paid amounts. items: $ref: '#/components/schemas/AlreadyPaidDetail' WebContext: type: object description: > The web context of the payment, containing information about the page on which the payment widget is displayed. additionalProperties: false properties: origin: description: The origin URL of the page on which the payment widget is displayed. type: string example: https://www.merchant.com referrer: description: Referrer of the HTTP page submitting the request. type: string example: https://www.merchant.com/checkout ClientSessionPartnerData: type: object description: | Partner-specific data attached to a client session. Not persisted: only forwarded to the payment partner. additionalProperties: false properties: web_context: $ref: '#/components/schemas/WebContext' ClientSessionApplication: description: Application used to create a client session. type: object required: - entity_id - amount - currency - order - shopper_redirection_url properties: entity_id: type: string format: uuid description: | ID of the entity that is using the orchestration API. This ID is provided by Purse. amount: type: integer example: 4299 minimum: 0 description: > 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: $ref: '#/components/schemas/Currency' capture_mode: $ref: '#/components/schemas/CaptureMode' capture_delay: $ref: '#/components/schemas/CaptureDelay' integration_mode: $ref: '#/components/schemas/IntegrationMode' shopper_redirection_url: type: string format: uri example: https://www.example.org/payment-callback?order_id=123456789 description: > URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET order: $ref: '#/components/schemas/Order' customer: $ref: '#/components/schemas/Customer' three_ds_authentication_options: $ref: '#/components/schemas/PaymentThreeDsAuthenticationOptions' webhook: $ref: '#/components/schemas/Webhook' allow_future_usage: type: boolean description: > 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. already_paid: $ref: '#/components/schemas/AlreadyPaid' partner_data: $ref: '#/components/schemas/ClientSessionPartnerData' example: 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: reference: '2090000000000' type: PERSON email: emily.rose.parker@example.org gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER birth_date: '1995-08-25' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2017-06-15T15:30:00+02:00' update_date_time: '2023-02-20T20:54:00+01:00' password_update_date_time: '2023-02-20T20:54:00+01:00' purchase_count_last_day: 0 purchase_count_last_six_months: 3 purchase_count_last_year: 8 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2023-10-30T15:33:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS purchase_total_amount: 12000 first_purchase_date_time: '2023-10-30T15:33:00+02:00' prior_purchase_date_time: '2024-12-30T15:33:00+02:00' order: reference: '123456789' net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true categories: - Clothing - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 categories: - Shipping marketplace_sellers: - name: Acme Corp reference: '#69-ACME' total_sales_count: 10000 total_sales_amount: 12000 registration_date_time: '2020-01-01T00:00:00+01:00' last_update_date_time: '2025-01-01T00:00:00+01:00' three_ds_authentication_options: challenge_indicator: NO_CHALLENGE_REQUESTED webhook: url: https://www.example.org/payment-hook headers: - name: x-order-id values: - '123456789' allow_future_usage: false ClientSessionStatus: type: string description: Status for a client session. enum: - CREATED - CHOICE_IN_PROGRESS - SUBMITTED - EXPIRED - ABORTED_BY_CUSTOMER - ABORTED_BY_MERCHANT CardNetwork: description: Network selected by the shopper to process the transaction. type: string enum: - VISA - MASTERCARD - CARTE_BANCAIRE - AMERICAN_EXPRESS - MAESTRO - ONEY example: VISA EligibleSolution: type: object description: Eligible solution for the client session. required: - partner - method properties: partner: type: string description: Payment solution partner. method: type: string description: Payment solution method. additional_data: type: object description: Additional data for the eligible solution. additionalProperties: true supported_brands: type: array description: Supported card brands for this solution. items: $ref: '#/components/schemas/CardNetwork' AuthorizationStatus: type: string description: Status for an authorization transaction. enum: - AUTHORIZED - PENDING - UNCERTAIN - ERROR - ABORTED - REFUSED PartnerTransaction: type: object required: - id - created_at - updated_at - amount - partner - method description: Representation of the partner transaction. properties: id: description: Id of the partner transaction (provided by Purse). type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 created_at: description: Partner transaction creation date time. type: string format: date-time updated_at: description: Partner transaction updated date time. type: string format: date-time amount: description: Amount of the partner transaction in currency minor unit. type: integer example: 4299 remaining_amount: description: >- Remaining amount to be processed for the transaction in currency minor unit. type: integer example: 4299 partner: description: Partner that processed the transaction. type: string example: ingenico method: description: Method used to process the transaction. type: string example: creditcard partner_reference: description: Reference of the transaction in the partner system. type: string example: AE0002ZCF7652QFF partner_status: description: Status of the transaction in the partner system. type: string example: 000.000.000 partner_status_description: description: Description of the status of the transaction in the partner system. type: string example: Transaction succeeded status_code: description: >- Purse status code. Provides an abstraction layer over partner_status and partner_status_description. type: string example: SUCCEEDED parent_partner_token: description: Token of the transaction in the partner system. type: string example: f8a333e9-cdc2-45d1-b9e5-dba95e00fa95 CommonCard: type: object properties: holder_name: description: Name of the card holder. type: string example: John Doe expiry_month: description: Expiry month of the card. String with two digits. type: string example: '01' expiry_year: description: Expiry year of the card. String with two digits. type: string example: '24' selected_network: $ref: '#/components/schemas/CardNetwork' CardType: description: Type of the card used to process the transaction. type: string enum: - VISA_DEBIT - VISA_CREDIT - VISA_ELECTRON - MASTERCARD_DEBIT - MASTERCARD_CREDIT - MAESTRO - AMERICAN_EXPRESS - CARTE_BANCAIRE - ONEY ThreeDSOutcome: description: >- 3DS information for the partner transaction (only provided for authorization transactions). type: object required: - eci - version - flow - ds_transaction_id - acs_transaction_id properties: eci: description: >- Electronic Commerce Indicator. Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder type: string enum: - '00' - '01' - '02' - '05' - '06' - '07' example: '01' version: description: 3DS version used to process the authentication. type: string example: 2.2.0 flow: description: 3DS flow used to process the authentication. type: string enum: - CHALLENGE - FRICTIONLESS example: CHALLENGE ds_transaction_id: description: >- Universally unique transaction identifier assigned by the DS (Directory Server) to identify a single transaction. type: string example: f8a333e9-cdc2-45d1-b9e5-dba95e00fa95 acs_transaction_id: description: >- Universally Unique transaction identifier assigned by the ACS (Access Control Server) to identify a single transaction. type: string example: f8a333e9-cdc2-45d1-b9e5-dba95e00fa95 cavv: description: >- Cardholder Authentication Verification Value. Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. type: string example: OTkxOTA4MDkxNjMzMTYwNTUwMzY= cavv_algorithm: description: >- Cardholder Authentication Verification Value Algorithm. Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. Only required for 3D Secure 1. Deprecated for 3D Secure 2 and beyond. type: string directory_response: description: >- Transaction status after ARes. Values could be `Y` for authenticated, `N` for failed authentication, `U` for authentication unavailable, `A` for attempted authentication. `C` for challenge required, `R` for rejected. type: string authentication_response: description: >- Transaction status after RReq (Challenge flow) Values could be `Y` for authenticated, `N` for failed authentication, `U` for authentication unavailable, `A` for attempted authentication. `C` for process incomplete, `R` for rejected, `D` for not enrolled, `I` for informationnal only. type: string trans_status_reason: description: >- Provides information on why the Transaction Status field has the specified value. See values `https://docs.3dsecure.io/3dsv2/specification_210.html#attr-ARes-transStatusReason` type: string card_holder_info: description: >- Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.” type: string Card: description: >- Card used to process the partner transaction (only provided for authorization transactions). type: object required: - bin - type - last_four_digits - holder_name - expiry_month - expiry_year - selected_network allOf: - $ref: '#/components/schemas/CommonCard' - type: object properties: bin: description: >- First 6/8 digits of the card number. (Bank Identification Number) type: string example: '513842' last_four_digits: description: Last 4 digits of the card number. type: string example: '1234' type: $ref: '#/components/schemas/CardType' country_code: description: Country code of the card. type: string example: FR three_ds: $ref: '#/components/schemas/ThreeDSOutcome' fingerprint: description: > An unique identifier of the card number. Useful to identify multiple customers' or the same customer's transactions where the same card was used. type: string example: F-coGuJQ55tUk8CnKGI9PX1T AuthorizePartnerTransaction: type: object description: Representation of the authorize operation partner transaction. required: - status allOf: - $ref: '#/components/schemas/PartnerTransaction' - type: object properties: status: $ref: '#/components/schemas/AuthorizationStatus' card: $ref: '#/components/schemas/Card' parent_partner_reference: description: Reference of the parent transaction in the partner system. type: string example: AE0002ZCF7652QFF partner_additional_data: description: Additional data provided by the partner. type: object example: opc: 3x002 save_token: description: >- Indicates if we requested to save the payment token for future usage. type: boolean example: true token_saved: description: Indicates if the payment token has been saved for future usage. type: boolean example: true wallet_token: description: Purse wallet token ID related to this authorization. type: string example: 1339f5a6-902b-4d2b-8b01-708caebeb76b Authorization: type: object description: Authorization information for a payment or client-session. properties: updated_at: description: Authorization updated date time. type: string format: date-time status: $ref: '#/components/schemas/AuthorizationStatus' partner_transactions: type: array items: $ref: '#/components/schemas/AuthorizePartnerTransaction' Link: type: object description: HATEOAS link. properties: method: type: string enum: - GET - POST - PUT - DELETE - PATCH href: type: string format: uri-reference example: href: >- https://api.example.com/v2/client-sessions/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET ClientSessionLinks: type: object description: HATEOAS links for a client session. required: - self properties: self: description: Link to the client session resource. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/client-sessions/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET payment: description: Link to the payment resource. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payments/03e0833d-ca1c-4ea6-8af1-23b5a96ae288 method: GET abort: description: Link to abort the client session. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/client-sessions/03e0833d-ca1c-4ea6-8af1-23b5a96ae288/abort method: POST hosted_page: description: Link to the hosted page. allOf: - $ref: '#/components/schemas/Link' - example: href: >- https://pay.purse-env.com/entities/8f093776-fb6d-11ef-b0f9-e6c49ab1fb0a/sessions/03e0833d-ca1c-4ea6-8af1-23b5a96ae288 method: GET payment_link: description: Link to the payment link. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payment-links/03e0833d-ca1c-4ea6-8af1-23b5a96ae288 method: GET ClientSession: type: object description: >- Object used by the front office to initiate a payment along with the widget. required: - id - entity_id - status - amount - currency - shopper_redirection_url - capture_mode - expires_at - widget - eligible_solutions - links properties: id: type: string format: uuid example: 9753ec77-fc16-4886-92af-c7dcf9b7352d status: $ref: '#/components/schemas/ClientSessionStatus' amount: type: integer example: 4299 description: >- Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR currency: $ref: '#/components/schemas/Currency' capture_mode: $ref: '#/components/schemas/CaptureMode' capture_delay: $ref: '#/components/schemas/CaptureDelay' integration_mode: $ref: '#/components/schemas/IntegrationMode' customer: $ref: '#/components/schemas/Customer' order: $ref: '#/components/schemas/Order' expires_at: type: string format: date-time example: '2024-08-25T10:42:59.123+02:00' entity_id: type: string format: uuid description: Entity ID for this ClientSession. shopper_redirection_url: type: string format: uri example: https://www.example.org/payment-callback?order_id=123456789 description: > URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET widget: description: Widget information to be provided to the frontend. type: object required: - data - js_url properties: data: type: string example: w9R5pLx2E7fqA3B1cV8z0YeL description: Data to be provided to the widget js_url: description: URL of the widget script to be loaded by the frontend. type: string format: uri example: https://widget.upstreampay.com/v3-current/UpStreamPay.js payment_id: description: >- ID of the payment created by the client session Only provided when the client session is in status SUBMITTED. type: string format: uuid example: 05c0d03f-2404-48c5-a521-bd5a57d3b355 payment_link_id: description: ID of the payment link that originated this client session, if any. type: string format: uuid eligible_solutions: description: List of eligible solutions for the client session. type: array items: $ref: '#/components/schemas/EligibleSolution' authorization: $ref: '#/components/schemas/Authorization' allow_future_usage: type: boolean description: > 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. already_paid: $ref: '#/components/schemas/AlreadyPaid' links: $ref: '#/components/schemas/ClientSessionLinks' AbortClientSessionApplication: type: object description: Contextual information in order to abort the client session required: - status properties: status: type: string enum: - ABORTED_BY_CUSTOMER - ABORTED_BY_MERCHANT example: status: ABORTED_BY_CUSTOMER Browser: type: object description: >- Browser information which should be collected by the partner front component. properties: referrer: type: string description: The referrer URL of the page where the payment was initiated. example: https://www.merchant.com/checkout accept_header: type: string description: Content of the HTTP accept headers example: text/html user_agent: type: string description: Content of the HTTP user-agent header example: Mozilla/4.0 (MSIE 6.0; Windows NT 5.0) color_depth: type: integer description: >- Value representing the bit depth of the color palette for displaying images, in bits per pixel format: int32 example: 32 java_enabled: type: boolean description: >- Boolean that represents the ability of the cardholder browser to execute Java example: true javascript_enabled: type: boolean description: >- Boolean that represents the ability of the cardholder browser to execute JavaScript example: true locale: type: string description: Value representing the browser language example: en-GB screen_height: type: integer description: Total height of the Cardholder’s screen in pixels format: int32 example: 1200 screen_width: type: integer description: Total width of the Cardholder’s screen in pixels format: int32 example: 1600 utc_time_zone: type: integer description: >- Time difference between UTC time and the Cardholder browser local time, in minutes format: int32 example: 60 DuplicateAuthorizationCandidate: description: Authorization to duplicate for this payment type: object required: - amount properties: amount: description: | Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR type: integer example: 4299 minimum: 0 exclusiveMinimum: true parent_partner_transaction_id: description: ID of the previously authorized partner transaction. type: string format: uuid example: 1a2b3c4d-1a2b-abcd-1234-123456789abc parent_payment_id: description: ID of the previously authorized payment. type: string format: uuid example: 9399c938-80e1-11ef-9de7-327d4a6ae82c DuplicateForeignAuthorizationCandidate: description: Foreign authorization to duplicate for this payment type: object required: - amount - partner - method properties: amount: description: | Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR type: integer example: 4299 minimum: 0 exclusiveMinimum: true partner: description: Partner that processed the transaction. type: string example: ingenico method: description: Method used to process the transaction. type: string example: creditcard parent_partner_token: description: Token generated by partner from a previous transaction type: string example: 64837-39372-32188 parent_partner_reference: description: Partner reference from a previous transaction type: string example: '123456789' anyOf: - required: - parent_partner_token - required: - parent_partner_reference Giving: type: object description: Giving (charitable donation) data attached to a split element. required: - campaign_reference - amount properties: campaign_reference: description: Reference of the giving campaign. type: string example: DOCA42CS7223226G5PKWZ963CL237H amount: description: | Giving amount in currency minor unit. For example, 1000 is 10.00 EUR. type: integer example: 1000 PartnerData: type: object description: | Partner-specific data attached to a split element. additionalProperties: false properties: giving: $ref: '#/components/schemas/Giving' point_of_sale_id: description: > In case of payment made in store, id of the point of sale in merchant system where the payment has been made. type: string example: TILL123 web_context: $ref: '#/components/schemas/WebContext' NewAuthorizationCandidate: description: New authorization for this payment type: object required: - amount - partner - method properties: amount: description: | Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR type: integer example: 4299 partner: type: string method: type: string vault_form_token: type: string card: allOf: - $ref: '#/components/schemas/CommonCard' - type: object properties: card_holder_birth_date: description: > Birth date of the card holder. This field is transmitted to the partner during the validate step. It is not stored nor returned in the card node of the response. Only for Oney. type: string example: '1995-08-25' three_ds_authentication_options: $ref: '#/components/schemas/PaymentThreeDsAuthenticationOptions' save_token: type: boolean description: > When `true`, the payment method used for this authorization will be saved in the customer's wallet for future usage, if supported by the partner. Default value is `false`. wallet_token: type: string description: | Token representing a payment method stored in a digital wallet. paypal: type: object properties: order_id: type: string setup_token_id: type: string applepay: type: object properties: token: type: string partner_data: $ref: '#/components/schemas/PartnerData' CreatePaymentApplication: description: Create payment type: object required: - amount - currency - entity_id - order properties: amount: description: | Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR type: integer example: 4299 currency: $ref: '#/components/schemas/Currency' entity_id: type: string format: uuid description: | ID of the entity that is using the orchestration API. This ID is provided by Purse. shopper_redirection_url: type: string format: uri example: https://www.example.org/payment-callback?order_id=123456789 description: > URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET capture_mode: $ref: '#/components/schemas/CaptureMode' capture_delay: $ref: '#/components/schemas/CaptureDelay' order: $ref: '#/components/schemas/Order' customer: $ref: '#/components/schemas/Customer' webhook: $ref: '#/components/schemas/Webhook' browser: $ref: '#/components/schemas/Browser' allow_future_usage: type: boolean description: > 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. split: type: array description: How payment was split over payment partners. items: oneOf: - $ref: '#/components/schemas/DuplicateAuthorizationCandidate' - $ref: '#/components/schemas/DuplicateForeignAuthorizationCandidate' - $ref: '#/components/schemas/NewAuthorizationCandidate' already_paid: $ref: '#/components/schemas/AlreadyPaid' example: entity_id: 5e3a0862-7cc3-4427-92ba-9e1e9595f571 amount: 12000 currency: EUR capture_mode: MANUAL order: reference: '123456789' net_amount: 12000 tax_amount: 2000 billing_address: gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER address_lines: - NextNow - 67 Rue de Luxembourg city: Lille postal_code: '59777' country_code: FR province_code: FR-HDF phone_number: '+33111111111' mobile_phone_number: '+33222222222' work_phone_number: '+33444444444' shipments: - net_amount: 12000 delivery_type: EXTERNAL_PICKUP delivery_quickness: REGULAR delivery_method_reference: '#1123-pickup' estimated_delivery_date_time: '2023-10-30T15:40:00+02:00' shipping_address: gender: FEMALE first_name: Rodriguez middle_name: Eios last_name: DESANTONS address_lines: - Av. de la roja 1676 city: Porto postal_code: '22000' country_code: PT province_code: PT-13 phone_number: '+33555555555' mobile_phone_number: '+33666666666' work_phone_number: '+33777777777' delivery_point_name: home item_lines: - type: PHYSICAL sku_reference: '2600218' name: Camiseta100 niño GYM brand: Quivio unit_gross_price: 5000 net_amount: 12000 quantity: 2 tax_amount: 2000 tax_rate: 20 seller_reference: '#42-ACME' seller_name: Acme Corp is_marketplace_seller: true - type: SHIPPING_FEES name: Transporte net_amount: 0 unit_gross_price: 0 quantity: 1 tax_amount: 0 tax_rate: 0 customer: reference: '2090000000000' type: PERSON email: emily.rose.parker@example.org gender: FEMALE first_name: Emily middle_name: Rose last_name: PARKER birth_date: '1995-08-25' ip_address: 203.0.113.195 locale: fr-FR account: creation_date_time: '2017-06-15T15:30:00+02:00' update_date_time: '2023-02-20T20:54:00+01:00' password_update_date_time: '2023-02-20T20:54:00+01:00' purchase_count_last_day: 0 purchase_count_last_six_months: 3 purchase_count_last_year: 8 authentication_method: MERCHANT_CREDENTIALS authentication_date_time: '2023-10-30T15:33:00+02:00' age_indicator: MORE_60_DAYS change_indicator: MORE_60_DAYS password_change_indicator: MORE_60_DAYS browser: user_agent: >- Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0 referrer: https://your_shop.com/order?id=1234 accept_header: text/html color_depth: 32 java_enabled: true javascript_enabled: true locale: fra screen_height: 1200 screen_width: 1600 utc_time_zone: 60 split: - amount: 3299 parent_payment_id: a1b2c3d4-abcd-1234-a1b2-123456abcdef - amount: 1000 method: giftcard partner: illicado PaymentTag: type: string description: | Overview : * `NOT` - No action performed * `PARTIALLY` - Action performed on partial available amount * `TOTALLY` - Action performed on total available amount enum: - NOT - PARTIALLY - TOTALLY PaymentTriggerOrigin: type: string description: > * `MERCHANT` - Operation triggered by an action from the merchant * `AUTHORIZATION` - Operation triggered by one step transaction (capture) * `ORCHESTRATOR` - Operation triggered by compensating transactions (void, refund) * `PARTNER` - Operation initiated by the payment partner itself (e.g. an automatic capture performed by the PSP at the end of the capture delay when `capture_mode` is `PARTNER`) enum: - MERCHANT - AUTHORIZATION - ORCHESTRATOR - PARTNER example: MERCHANT PaymentOperationStatus: type: string description: Status for a payment action. enum: - SUCCESS - FAILURE - PENDING - CONFLICT - UNCERTAIN PaymentTransactionStatus: type: string description: Status of the partner transaction. enum: - SUCCESS - FAILURE - PENDING - UNCERTAIN example: SUCCESS OperationPartnerTransaction: type: object description: >- Representation of a payment operation partner transaction. (capture, refund, void) required: - status allOf: - $ref: '#/components/schemas/PartnerTransaction' - type: object properties: status: $ref: '#/components/schemas/PaymentTransactionStatus' PaymentOperationShipment: type: object description: >- Information regarding shipping / delivery and the items to be shipped. This object is only valued for payment operations. properties: net_amount: type: integer description: Total amount of the shipment in currency minor unit. example: 4299 item_lines: type: array description: List of all items for the shipment. items: $ref: '#/components/schemas/ItemLine' PaymentOperationOrder: type: object description: >- Information regarding the order and the items to be purchased. This object is only valued for payment operations. properties: shipments: type: array description: List of all shipments for the order. items: $ref: '#/components/schemas/PaymentOperationShipment' additional_data: type: object description: Additional data for the order as key-value pairs PaymentOperation: type: object required: - id - created_at - updated_at - amount - status - partner_transactions - triggered_by description: >- The operation can be a capture, a refund or a void. The operation can be split in multiple partner transactions. properties: id: description: ID of the operation (provided by Purse). type: string format: uuid example: e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1 amount: description: Amount of the operation in currency minor unit. type: integer example: 4299 created_at: description: Operation creation date time. type: string format: date-time example: '2020-08-25T10:42:59.123+02:00' updated_at: description: Operation update date time. type: string format: date-time example: '2020-08-25T10:42:59.123+02:00' triggered_by: $ref: '#/components/schemas/PaymentTriggerOrigin' merchant_reference: description: Reference of the operation in the merchant system. type: string example: CAP#1223445 status: $ref: '#/components/schemas/PaymentOperationStatus' partner_transactions: description: List of all partner transactions for the operation. type: array items: $ref: '#/components/schemas/OperationPartnerTransaction' order: $ref: '#/components/schemas/PaymentOperationOrder' Captures: description: List of all capture operations for a payment. type: array items: $ref: '#/components/schemas/PaymentOperation' Voids: description: List of all void operations for a payment. type: array items: $ref: '#/components/schemas/PaymentOperation' Refunds: description: List of all refund operations for a payment. type: array items: $ref: '#/components/schemas/PaymentOperation' AuthenticationStatus: type: string description: | Overview: * `CREATED` - 3DS challenge has not been initiated yet. * `IN_PROGRESS` - 3DS challenge is in progress, we're waiting for the client to be redirected to us. * `SUCCESS` - 3DS challenge completed with success, the client has been authorized. * `FAILURE` - 3DS challenge completed but the client has not been authorized. * `CANCELLED` - 3DS challenge has been cancelled by the client. * `ERROR` - 3DS challenge fails due to an error. enum: - CREATED - IN_PROGRESS - SUCCESS - FAILURE - CANCELLED - ERROR PartnerAuthentication: type: object description: Representation of the partner authentication. required: - id - status - amount - partner_status properties: id: type: string format: uuid description: ID of the authentication (provided by Purse). example: f8a333e9-cdc2-45d1-b9e5-dba95e00fa95 status: $ref: '#/components/schemas/AuthenticationStatus' amount: type: integer description: Amount of the operation in currency minor unit. example: 1000 partner_status: type: string description: Partner status for the authentication. example: AUTHENTICATED partner_status_description: type: string description: >- Description of the status of the authentication in the partner system. example: Successful authentication card: $ref: '#/components/schemas/Card' Authentication: type: object description: Authentication information for a payment when 3DS if performed by Purse. required: - updated_at - status properties: updated_at: description: Authentication update date time. type: string format: date-time status: $ref: '#/components/schemas/AuthenticationStatus' partner_authentications: type: array items: $ref: '#/components/schemas/PartnerAuthentication' PaymentAmounts: type: object description: Amount details for a payment. required: - authorize_pending - total_authorized - total_voided - available_to_void - total_captured - available_to_capture - total_refunded - available_to_refund properties: authorize_pending: description: >- Total amount waiting for authorization. This amount is not yet authorized. type: integer example: 0 total_authorized: description: >- Total amount authorized for the payment. This amount does not change once the payment is authorized. type: integer example: 4299 total_voided: description: >- Total amount voided for the payment. Only includes voided amounts that have been successfully processed. type: integer example: 299 available_to_void: description: Total amount available to be voided for the payment. type: integer example: 1000 total_captured: description: >- Total amount captured for the payment. Only includes captured amounts that have been successfully processed. type: integer example: 3000 available_to_capture: description: >- Total amount available to be captured or void for this partner transaction. type: integer example: 1000 total_refunded: description: >- Total amount refunded for the payment. Only includes refunded amounts that have been successfully processed. type: integer example: 0 available_to_refund: description: Total amount available to be refunded for the payment. type: integer example: 3000 example: authorize_pending: 0 total_authorized: 4299 total_voided: 299 available_to_void: 1000 total_captured: 3000 available_to_capture: 1000 total_refunded: 0 available_to_refund: 3000 PaymentLinks: type: object description: HATEOAS links for a payment. required: - self properties: self: description: Link to the payment resource. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/client-sessions/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET capture: description: Link to capture the payment. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/captures method: POST refund: description: Link to refund the payment. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/refunds method: POST void: description: Link to void the payment. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/voids method: POST payment_link: description: Link to the payment link. allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payment-links/03e0833d-ca1c-4ea6-8af1-23b5a96ae288 method: GET PaymentSplitElement: type: object description: Split of a payment over a single payment partner/solution. properties: partner: description: Payment partner used to process the payment. type: string example: ingenico method: description: Payment method used to process the payment. type: string example: creditcard amount: description: Amount of the payment in currency minor unit. type: integer example: 4299 parent_partner_transaction_id: description: ID of the previously authorized partner transaction. type: string format: uuid example: 1a2b3c4d-1a2b-abcd-1234-123456789abc parent_payment_id: description: ID of the previously authorized payment. type: string format: uuid example: 9399c938-80e1-11ef-9de7-327d4a6ae82c parent_partner_token: description: Token generated by partner from a previous transaction type: string example: 64837-39372-32188 parent_partner_reference: description: Partner reference from a previous transaction type: string Payment: description: Representation of a payment. type: object required: - id - created_at - amount - currency - version - entity_id - overview - capture_mode - authorization - captures - voids - refunds - amounts - split - links - allow_future_usage properties: id: description: ID of the payment provided by Purse. type: string format: uuid created_at: description: Payment creation date time. type: string format: date-time overview: type: object required: - consumed - captured - voided - refunded properties: consumed: $ref: '#/components/schemas/PaymentTag' captured: $ref: '#/components/schemas/PaymentTag' voided: $ref: '#/components/schemas/PaymentTag' refunded: $ref: '#/components/schemas/PaymentTag' client_session_id: description: ID of the client session that created the payment. type: string format: uuid payment_link_id: description: ID of the payment link that originated this payment. type: string format: uuid entity_id: type: string format: uuid description: Entity ID for this ClientSession. version: type: integer example: 3 description: Version of the payment resource. order_reference: description: Reference of the order provided by the merchant. type: string example: order_01 order: $ref: '#/components/schemas/Order' customer: $ref: '#/components/schemas/Customer' amount: description: Amount of the payment in currency minor unit. type: integer example: 4299 currency: $ref: '#/components/schemas/Currency' capture_mode: $ref: '#/components/schemas/CaptureMode' capture_delay: $ref: '#/components/schemas/CaptureDelay' captures: $ref: '#/components/schemas/Captures' voids: $ref: '#/components/schemas/Voids' refunds: $ref: '#/components/schemas/Refunds' authorization: $ref: '#/components/schemas/Authorization' authentication: $ref: '#/components/schemas/Authentication' amounts: $ref: '#/components/schemas/PaymentAmounts' links: $ref: '#/components/schemas/PaymentLinks' browser: $ref: '#/components/schemas/Browser' split: type: array description: How payment was split over payment partners. items: $ref: '#/components/schemas/PaymentSplitElement' webhook: $ref: '#/components/schemas/Webhook' allow_future_usage: type: boolean description: > 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. already_paid: $ref: '#/components/schemas/AlreadyPaid' redirection: type: object description: Redirection information for the payment. properties: method: type: string enum: - GET - POST href: type: string format: uri media_type: description: Media type of the redirection link. type: string enum: - application/json - application/x-www-form-urlencoded - text/html body: description: Body to be used for redirection. type: string example: href: >- https://pay.purse-env.com/entities/8f093776-fb6d-11ef-b0f9-e6c49ab1fb0a/sessions/03e0833d-ca1c-4ea6-8af1-23b5a96ae288 method: GET media_type: application/json body: '{"data": "json data to be used for redirection"}' IdempotencyProblemDetail: title: An RFC 7807 problem object type: object properties: type: type: string format: uri-reference description: A URI reference that identifies the problem type. title: type: string description: A short, human-readable summary of the problem type. status: type: integer description: > The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 100 maximum: 599 instance: type: string format: uri-reference description: > A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. PaymentIdempotencyProblemDetail: allOf: - $ref: '#/components/schemas/IdempotencyProblemDetail' - type: object properties: resource_id: type: string format: uuid description: >- The `resource_id` corresponds to a payment ID that has already been processed with the specified idempotency key. example: 1a14962c-bdcf-49d1-8673-e75dfb48013f ByDefaultPriority: type: object required: - amount not: anyOf: - required: - priority properties: priority: description: > Priority of the operation. The priority is used to determine the order in which the operations are processed. type: array items: $ref: '#/components/schemas/EligibleSolutionDetails' - required: - partner_transaction_id properties: partner_transaction_id: type: string format: uuid example: 1a2b3c4d-1a2b-abcd-1234-123456789abc properties: amount: type: integer example: 10 minimum: 0 exclusiveMinimum: true description: Amount to be processed for the called operation. order: $ref: '#/components/schemas/PaymentOperationOrder' merchant_reference: type: string example: CAP#1223445 description: Reference of the operation in the merchant system. ByCustomPriority: description: order the payment operation by priority type: object required: - amount - priority not: required: - partner_transaction_id properties: partner_transaction_id: type: string format: uuid example: 1a2b3c4d-1a2b-abcd-1234-123456789abc properties: amount: type: integer example: 10 minimum: 0 exclusiveMinimum: true description: Amount to be processed for the called operation. order: $ref: '#/components/schemas/PaymentOperationOrder' merchant_reference: type: string example: CAP#1223445 description: Reference of the operation in the merchant system. priority: description: > Priority of the operation. The priority is used to determine the order in which the operations are processed. type: array items: $ref: '#/components/schemas/EligibleSolutionDetails' ByPartnerTransactionId: description: execute the payment operation by partner transaction id type: object required: - amount - partner_transaction_id not: required: - priority properties: priority: description: > Priority of the operation. The priority is used to determine the order in which the operations are processed. type: array items: $ref: '#/components/schemas/EligibleSolutionDetails' properties: amount: type: integer example: 10 minimum: 0 exclusiveMinimum: true description: Amount to be processed for the called operation. order: $ref: '#/components/schemas/PaymentOperationOrder' merchant_reference: type: string example: CAP#1223445 description: Reference of the operation in the merchant system. partner_transaction_id: type: string format: uuid example: 1a2b3c4d-1a2b-abcd-1234-123456789abc PaymentOperationApplication: type: object oneOf: - $ref: '#/components/schemas/ByDefaultPriority' - $ref: '#/components/schemas/ByCustomPriority' - $ref: '#/components/schemas/ByPartnerTransactionId' OperationIdempotencyProblemDetail: allOf: - $ref: '#/components/schemas/IdempotencyProblemDetail' - type: object properties: resource_id: type: string format: uuid description: >- The `resource_id` corresponds to a payment operation ID (capture/void/refund) that has already been processed with the specified idempotency key. example: 2e3a6516-0ec4-4a5b-92b0-7bb9693e82c1 PaymentLinkApplication: description: Application used to create a payment link type: object required: - entity_id - expires_at - amount - currency - order - shopper_redirection_url properties: entity_id: type: string format: uuid description: | ID of the entity that is using the orchestration API. This ID is provided by Purse. expires_at: type: string format: date-time example: '2024-08-25T10:42:59.123+02:00' description: | Expiration date time of the payment link. After this date time, the link will no longer be valid. amount: type: integer example: 4299 minimum: 0 description: > 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: $ref: '#/components/schemas/Currency' capture_mode: $ref: '#/components/schemas/CaptureMode' shopper_redirection_url: type: string format: uri example: https://www.example.org/payment-callback?order_id=123456789 description: > URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET order: $ref: '#/components/schemas/Order' customer: $ref: '#/components/schemas/Customer' three_ds_authentication_options: $ref: '#/components/schemas/PaymentThreeDsAuthenticationOptions' webhook: $ref: '#/components/schemas/Webhook' allow_future_usage: type: boolean description: > 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. already_paid: $ref: '#/components/schemas/AlreadyPaid' PaymentLinkStatus: type: string description: Status for a payment link. enum: - CREATED - OPENED - PAID - EXPIRED - CANCELLED PaymentLinkHateoasLinks: type: object description: HATEOAS links for a payment link. required: - self properties: self: description: Link to the payment links resource allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payment-links/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET customer_url: description: Link for the customer to use the payment link allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payment/link/9a14962c-bdcf-49d1-8673-e75dfb48013f method: GET cancel: description: Link to cancel the payment link allOf: - $ref: '#/components/schemas/Link' - example: href: /v2/payment-links/9a14962c-bdcf-49d1-8673-e75dfb48013f/cancel method: POST PaymentLink: type: object description: >- Object used by the front office to initiate a payment along with the widget. required: - id - version - entity_id - status - amount - currency - shopper_redirection_url - capture_mode - expires_at - links properties: id: type: string format: uuid example: 9753ec77-fc16-4886-92af-c7dcf9b7352d version: type: integer example: 3 description: Version of the payment link resource. status: $ref: '#/components/schemas/PaymentLinkStatus' payment_attempts: type: array description: List of payment attempts related to this payment link. items: type: object required: - client_session_id - client_session_status properties: payment_id: type: string format: uuid example: 9a14962c-bdcf-49d1-8673-e75dfb48013f authorization_status: $ref: '#/components/schemas/AuthorizationStatus' client_session_id: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 client_session_status: $ref: '#/components/schemas/ClientSessionStatus' amount: type: integer example: 4299 description: >- Amount to be payed in currency minor unit. For example, 4299 is 42.99 EUR currency: $ref: '#/components/schemas/Currency' capture_mode: $ref: '#/components/schemas/CaptureMode' customer: $ref: '#/components/schemas/Customer' order: $ref: '#/components/schemas/Order' expires_at: type: string format: date-time example: '2026-08-25T10:42:59.123+02:00' entity_id: type: string format: uuid description: Entity ID for this payment link. shopper_redirection_url: type: string format: uri example: https://www.example.org/payment-callback?order_id=123456789 description: > URL to which the shopper will be redirected after the payment process. Redirection will use HTTP GET allow_future_usage: type: boolean description: > 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. already_paid: $ref: '#/components/schemas/AlreadyPaid' links: $ref: '#/components/schemas/PaymentLinkHateoasLinks' webhook: $ref: '#/components/schemas/Webhook'