ProcessOut Invoices API
The Invoices API from ProcessOut — 6 operation(s) for invoices.
OpenAPI Specification
openapi: 3.1.0
info:
title: ProcessOut Balances Invoices API
version: 1.0.3
description: ProcessOut is a payments technical layer that standardizes merchant connections to 100+ payment providers (PSPs/APMs), with a PCI DSS card vault, tokenization for recurring payments, dynamic/no-code checkout, ML-based smart routing, analytics and transaction reconciliation. Authentication is HTTP Basic using a project ID (username) and secret API key (password). This OpenAPI 3.1 description was assembled by API Evangelist from the per-operation OpenAPI fragments ProcessOut publishes in each ReadMe API-reference page.
contact:
email: help@processout.com
url: https://docs.processout.com
servers:
- url: https://api.processout.com
description: Production
security:
- sec0: []
tags:
- name: Invoices
paths:
/invoices/{invoice_id}/authorize:
post:
summary: Authorizing an invoice
description: ''
operationId: authorizing-an-invoice
parameters:
- name: invoice_id
in: path
description: The invoice ID generated by ProcessOut during the invoice creation
schema:
type: string
required: true
- name: Idempotency-Key
in: header
description: Unique key to your request that will be used for idempotency
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
source:
type: string
description: Source used to authorization the payment. Can be a card, a token or a gateway request.
save_source:
type: boolean
description: Optional if you want us to save the payment source (card or APM) by creating a customer token during the authorisation
initial_scheme_transaction_id:
type: string
description: Override the scheme ID
incremental:
type: boolean
description: Request a pre-authorization that can be incremented at a later stage
default: false
preferred_scheme:
type: string
description: 'Scheme the customer would prefer to process transaction on. Ex: `carte bancaire`. If there is already a default set on the card object, then you can override it using this field. Please use `none` if you wish to override it back to empty for this request. <br>_Only supported on compatible payment providers_.'
external_three_d_s:
type: object
description: Allow you to pass 3DS data obtained from an external provider outside of ProcessOut. Please contact your CSM to ensure the PSPs you are routing towards support this functionality.
properties:
xid:
type: string
description: Base64 encoded XID - Transaction identifier resulting from authentication processing.
trans_status:
type: string
description: AResTransStatus (fingerprint) or CResTransStatus (challenge) from the 3DS response
eci:
type: string
description: Electronic Commerce Indicator
cavv:
type: string
description: Cardholder Authentication Verification Value (CAVV), Authentication Verification Value (AVV) or Universal Cardholder Authentication Field (UCAF). Must be in Base64 encoded format.
ds_trans_id:
type: string
description: Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
version:
type: string
description: 3DS version used e.g. 2.2.0
authentication_flow:
type: string
description: 'Denotes the flow which 3DS took. Frictionless meaning no challenge taken place from the customer''s point of view. Accepted values: `FRICTIONLESS` or `CHALLENGE`'
enum:
- '"FRICTIONLESS"'
- '"CHALLENGE"'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"success\": true,\n \"transaction\": {\n \"id\": \"tr_7FPylQ0EOrLpcYw3E6OhdCEVnRCdFqoZ\",\n \"project_id\": \"proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S\",\n \"customer_id\": \"cust_MFW0Z4jtoXLfADjPKlVRl5LxWkCTUgRw\",\n \"routing_tags\": [\"route-1\", \"route-2\"],\n \"fraud_service_results\": null,\n \"operations\": [\n {\n \"id\": \"tr_op_ufSmIq7kU3bB6bVoiislmqeMNmxquzpX\",\n \"transaction_id\": \"tr_7FPylQ0EOrLpcYw3E6OhdCEVnRCdFqoZ\",\n \"authenticated_transaction_id\": \"8284686045\",\n \"authorization_code\": null,\n \"gateway_configuration_id\": \"gway_conf_c23e011db34f4bac44e051840dfa3783\",\n \"card_id\": \"card_TVeLAxjOaiHzru3m7T1o0ZLUg6cXIQe8\",\n \"amount\": \"29\",\n \"amount_local\": \"31.8321371\",\n \"currency\": \"EUR\",\n \"is_attempt\": false,\n \"has_failed\": false,\n \"is_accountable\": false,\n \"type\": \"request\",\n \"metadata\": {\n \"is_sale\": \"false\"\n },\n \"error_code\": null,\n \"error_message\": null,\n \"payment_type\": \"card\",\n \"eci\": null,\n \"is_on_us\": null,\n \"arn\": null,\n \"scheme_id\": \"8284686045\",\n \"initial_scheme_transaction_id\": \"\",\n \"gateway_operation_id\": \"\",\n \"gateway_data\": {\n \"token\": \"test-valid\"\n },\n \"chargeback_reason\": null,\n \"created_at\": \"2023-04-21T20:24:43.342363262Z\",\n \"merchant_advice_code\": null,\n \"merchant_advice_reason\": null,\n \"recommendation_code\": null,\n \"recommendation_reason\": null,\n \"challenge_indicator\": \"no-preference\",\n \"sca_exemption_reason\": \"\"\n },\n {\n \"id\": \"tr_op_FVJD7TG7tBrldTEoSRNr0uA48XQgskVZ\",\n \"transaction_id\": \"tr_7FPylQ0EOrLpcYw3E6OhdCEVnRCdFqoZ\",\n \"authenticated_transaction_id\": \"8284686045\",\n \"authorization_code\": null,\n \"gateway_configuration_id\": \"gway_conf_c23e011db34f4bac44e051840dfa3783\",\n \"card_id\": \"card_TVeLAxjOaiHzru3m7T1o0ZLUg6cXIQe8\",\n \"amount\": \"29\",\n \"amount_local\": \"31.8321371\",\n \"currency\": \"EUR\",\n \"is_attempt\": true,\n \"has_failed\": false,\n \"is_accountable\": false,\n \"type\": \"authorization\",\n \"metadata\": {\n \"is_sale\": \"false\"\n },\n \"error_code\": null,\n \"error_message\": null,\n \"payment_type\": \"card\",\n \"acquirer_name\": null,\n \"eci\": null,\n \"merchant_account_id\": null,\n \"is_on_us\": null,\n \"arn\": null,\n \"scheme_id\": \"8284686045\",\n \"initial_scheme_transaction_id\": \"\",\n \"gateway_operation_id\": \"test-valid-17580cef700c691a\",\n \"gateway_data\": {\n \"token\": \"test-valid\"\n },\n \"chargeback_reason\": null,\n \"created_at\": \"2023-04-21T20:24:43.342417133Z\",\n \"merchant_advice_code\": null,\n \"merchant_advice_reason\": null,\n \"recommendation_code\": null,\n \"recommendation_reason\": null,\n \"challenge_indicator\": \"no-preference\",\n \"sca_exemption_reason\": \"\"\n },\n {\n \"id\": \"tr_op_fLlh7plcTzPelsHiVRoTf6qaURfZLDTm\",\n \"transaction_id\": \"tr_7FPylQ0EOrLpcYw3E6OhdCEVnRCdFqoZ\",\n \"authenticated_transaction_id\": \"8284686045\",\n \"authorization_code\": null,\n \"gateway_configuration_id\": \"gway_conf_c23e011db34f4bac44e051840dfa3783\",\n \"card_id\": \"card_TVeLAxjOaiHzru3m7T1o0ZLUg6cXIQe8\",\n \"amount\": \"29\",\n \"amount_local\": \"31.8321371\",\n \"currency\": \"EUR\",\n \"is_attempt\": false,\n \"has_failed\": false,\n \"is_accountable\": false,\n \"type\": \"authorization\",\n \"metadata\": {\n \"is_sale\": \"false\"\n },\n \"error_code\": null,\n \"error_message\": null,\n \"payment_type\": \"card\",\n \"acquirer_name\": null,\n \"eci\": null,\n \"merchant_account_id\": null,\n \"is_on_us\": null,\n \"arn\": null,\n \"scheme_id\": \"8284686045\",\n \"initial_scheme_transaction_id\": \"\",\n \"gateway_operation_id\": \"test-valid-17580cef700c691a\",\n \"gateway_data\": {\n \"token\": \"test-valid\"\n },\n \"chargeback_reason\": null,\n \"created_at\": \"2023-04-21T20:24:43.342463204Z\",\n \"merchant_advice_code\": null,\n \"merchant_advice_reason\": null,\n \"recommendation_code\": null,\n \"recommendation_reason\": null,\n \"challenge_indicator\": \"no-preference\",\n \"sca_exemption_reason\": \"\"\n }\n ],\n \"name\": \"Amazing Product\",\n \"currency\": \"EUR\",\n \"metadata\": {\n \"fruit\": \"banana\"\n },\n \"sandbox\": true,\n \"created_at\": \"2023-04-21T20:24:37.850357Z\",\n \"invoice_id\": \"iv_RRW65C1I2jAGiFuwhEtW5UGU1tMkBRBS\",\n \"gateway_name\": \"sandbox\",\n \"status\": \"authorized\",\n \"gateway_configuration_id\": \"gway_conf_c23e011db34f4bac44e051840dfa3783\",\n \"card_id\": \"card_TVeLAxjOaiHzru3m7T1o0ZLUg6cXIQe8\",\n \"error_code\": null,\n \"error_message\": null,\n \"payment_type\": \"card\",\n \"eci\": null,\n \"cvc_check\": \"passed\",\n \"avs_check\": \"passed\",\n \"card_checks\": {\n \"cvc_check\": \"passed\",\n \"cvc_check_reason\": null,\n \"avs_check\": \"passed\",\n \"avs_postal_check\": \"passed\",\n \"avs_postal_check_reason\": null,\n \"avs_street_check\": \"passed\",\n \"avs_street_check_reason\": null,\n \"avs_name_check\": \"passed\",\n \"avs_name_check_reason\": null\n },\n \"amount\": \"29\",\n \"amount_local\": \"31.8321371\",\n \"authorized_amount\": \"29\",\n \"authorized_amount_local\": \"31.8321371\",\n \"captured_amount\": \"0\",\n \"captured_amount_local\": \"0\",\n \"available_amount\": \"0\",\n \"available_amount_local\": \"0\",\n \"incremented_amount\": \"0\",\n \"incremented_amount_local\": \"0\",\n \"refunded_amount\": \"0\",\n \"refunded_amount_local\": \"0\",\n \"authorized_at\": \"2023-04-21T20:24:43.342463204Z\",\n \"captured_at\": null,\n \"refunded_at\": null,\n \"voided_at\": null,\n \"chargedback_at\": null,\n \"received_fraud_notification\": false,\n \"received_retrieval_request\": false,\n \"acquirer_name\": null,\n \"attempts_count\": 1,\n \"authorized\": true,\n \"captured\": false,\n \"refunded\": false,\n \"voided\": false,\n \"chargedback\": false,\n \"merchant_advice_code\": null,\n \"merchant_advice_reason\": null,\n \"recommendation_code\": null,\n \"recommendation_reason\": null,\n \"scheme_id\": \"8284686045\",\n \"initial_scheme_transaction_id\": null,\n \"sca\": {\n \"scope\": \"out-of-scope\",\n \"out_of_scope_reason\": \"mit\",\n \"inscope_compliance\": \"not-applicable\",\n \"challenge_result\": \"honoured\",\n \"exemption_result\": \"no-exemption-reason-set\"\n },\n \"refunds\": null,\n \"duplicate_distance_seconds\": null\n }\n}"
schema:
type: object
properties:
success:
type: boolean
example: true
default: true
transaction:
type: object
properties:
id:
type: string
example: tr_7FPylQ0EOrLpcYw3E6OhdCEVnRCdFqoZ
project_id:
type: string
example: proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S
customer_id:
type: string
example: cust_MFW0Z4jtoXLfADjPKlVRl5LxWkCTUgRw
routing_tags:
type: array
items:
type: string
example: route-1
fraud_service_results: {}
operations:
type: array
items:
type: object
properties:
id:
type: string
example: tr_op_ufSmIq7kU3bB6bVoiislmqeMNmxquzpX
transaction_id:
type: string
example: tr_7FPylQ0EOrLpcYw3E6OhdCEVnRCdFqoZ
authenticated_transaction_id:
type: string
example: '8284686045'
authorization_code: {}
gateway_configuration_id:
type: string
example: gway_conf_c23e011db34f4bac44e051840dfa3783
card_id:
type: string
example: card_TVeLAxjOaiHzru3m7T1o0ZLUg6cXIQe8
amount:
type: string
example: '29'
amount_local:
type: string
example: '31.8321371'
currency:
type: string
example: EUR
is_attempt:
type: boolean
example: false
default: true
has_failed:
type: boolean
example: false
default: true
is_accountable:
type: boolean
example: false
default: true
type:
type: string
example: request
metadata:
type: object
properties:
is_sale:
type: string
example: 'false'
error_code: {}
error_message: {}
payment_type:
type: string
example: card
eci: {}
is_on_us: {}
arn: {}
scheme_id:
type: string
example: '8284686045'
initial_scheme_transaction_id:
type: string
example: ''
gateway_operation_id:
type: string
example: ''
gateway_data:
type: object
properties:
token:
type: string
example: test-valid
chargeback_reason: {}
created_at:
type: string
example: '2023-04-21T20:24:43.342363262Z'
merchant_advice_code: {}
merchant_advice_reason: {}
recommendation_code: {}
recommendation_reason: {}
challenge_indicator:
type: string
example: no-preference
sca_exemption_reason:
type: string
example: ''
name:
type: string
example: Amazing Product
currency:
type: string
example: EUR
metadata:
type: object
properties:
fruit:
type: string
example: banana
sandbox:
type: boolean
example: true
default: true
created_at:
type: string
example: '2023-04-21T20:24:37.850357Z'
invoice_id:
type: string
example: iv_RRW65C1I2jAGiFuwhEtW5UGU1tMkBRBS
gateway_name:
type: string
example: sandbox
status:
type: string
example: authorized
gateway_configuration_id:
type: string
example: gway_conf_c23e011db34f4bac44e051840dfa3783
card_id:
type: string
example: card_TVeLAxjOaiHzru3m7T1o0ZLUg6cXIQe8
error_code: {}
error_message: {}
payment_type:
type: string
example: card
eci: {}
cvc_check:
type: string
example: passed
avs_check:
type: string
example: passed
card_checks:
type: object
properties:
cvc_check:
type: string
example: passed
cvc_check_reason: {}
avs_check:
type: string
example: passed
avs_postal_check:
type: string
example: passed
avs_postal_check_reason: {}
avs_street_check:
type: string
example: passed
avs_street_check_reason: {}
avs_name_check:
type: string
example: passed
avs_name_check_reason: {}
amount:
type: string
example: '29'
amount_local:
type: string
example: '31.8321371'
authorized_amount:
type: string
example: '29'
authorized_amount_local:
type: string
example: '31.8321371'
captured_amount:
type: string
example: '0'
captured_amount_local:
type: string
example: '0'
available_amount:
type: string
example: '0'
available_amount_local:
type: string
example: '0'
incremented_amount:
type: string
example: '0'
incremented_amount_local:
type: string
example: '0'
refunded_amount:
type: string
example: '0'
refunded_amount_local:
type: string
example: '0'
authorized_at:
type: string
example: '2023-04-21T20:24:43.342463204Z'
captured_at: {}
refunded_at: {}
voided_at: {}
chargedback_at: {}
received_fraud_notification:
type: boolean
example: false
default: true
received_retrieval_request:
type: boolean
example: false
default: true
acquirer_name: {}
attempts_count:
type: integer
example: 1
default: 0
authorized:
type: boolean
example: true
default: true
captured:
type: boolean
example: false
default: true
refunded:
type: boolean
example: false
default: true
voided:
type: boolean
example: false
default: true
chargedback:
type: boolean
example: false
default: true
merchant_advice_code: {}
merchant_advice_reason: {}
recommendation_code: {}
recommendation_reason: {}
scheme_id:
type: string
example: '8284686045'
initial_scheme_transaction_id: {}
sca:
type: object
properties:
scope:
type: string
example: out-of-scope
out_of_scope_reason:
type: string
example: mit
inscope_compliance:
type: string
example: not-applicable
challenge_result:
type: string
example: honoured
exemption_result:
type: string
example: no-exemption-reason-set
refunds: {}
duplicate_distance_seconds: {}
'401':
description: '401'
content:
application/json:
examples:
Result:
value: "{\n \"success\": false,\n \"message\": \"Could not read your project ID. Please make sure to use Basic HTTP authentication using your project ID as the username. If you have any questions, feel free to ask for help at help@processout.com!\",\n \"error_type\": \"request.authentication.invalid\"\n}"
schema:
type: object
properties:
success:
type: boolean
example: false
default: true
message:
type: string
example: Could not read your project ID. Please make sure to use Basic HTTP authentication using your project ID as the username. If you have any questions, feel free to ask for help at help@processout.com!
error_type:
type: string
example: request.authentication.invalid
'404':
description: '404'
content:
application/json:
examples:
Result:
value: "{\n \"error_type\": \"resource.invoice.not-found\",\n \"message\": \"The invoice could not be found.\",\n \"success\": false\n}"
schema:
type: object
properties:
error_type:
type: string
example: resource.invoice.not-found
message:
type: string
example: The invoice could not be found.
success:
type: boolean
example: false
default: true
'410':
description: '410'
content:
application/json:
examples:
Transaction error:
value: "{\n \"error_type\": \"card.do-not-honor\",\n \"message\": \"The bank has returned a do-not-honor error\",\n \"success\": false\n}"
schema:
type: object
properties:
error_type:
type: string
example: card.do-not-honor
message:
type: string
example: The bank has returned a do-not-honor error
success:
type: boolean
example: false
default: true
4XX:
description: 4XX
content:
application/json:
examples:
Result:
value: "{\n \"error_type\": \"*Error code*\",\n \"message\": \"*Error message*\",\n \"success\": false\n}"
schema:
type: object
properties:
error_type:
type: string
example: '*Error code*'
message:
type: string
example: '*Error message*'
success:
type: boolean
example: false
default: true
x-readme:
code-samples:
- language: node
code: "var ProcessOut = require(\"processout\");\nvar client = new ProcessOut(\n \"test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x\",\n \"key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB\");\n\n// The source could also be a token tok_fKK4btSG7wd13ZZaevzhMcuNbpjcu1Zy\ninvoice.authorize(\"card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ\", {\n // optional if you want us to auto capture for you\n \"auto_capture_at\": \"2022-10-02T15:00:00Z\"\n}).then(\n function(transaction) {\n // The invoice was authorized and returned a transaction\n\n }, function(err) {\n // The invoice could not be authorized\n });"
name: node.js
- language: python
code: "import processout\nclient = processout.ProcessOut(\n \"test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x\", \n \"key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB\")\n\n# The source could also be a token tok_fKK4btSG7wd13ZZaevzhMcuNbpjcu1Zy\ntransaction = invoice.authorize(\"card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ\", {\n # optional if you want us to auto capture for you\n \"auto_capture_at\": \"2022-10-02T15:00:00Z\"\n})"
- language: ruby
code: "require \"processout\"\nclient = ProcessOut::Client.new(\n \"test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x\", \n \"key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB\")\n\n# The source could also be a token tok_fKK4btSG7wd13ZZaevzhMcuNbpjcu1Zy\ntransaction = invoice.authorize(\"card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ\", (\n # optional if you want us to auto capture for you\n auto_capture_at: \"2022-10-02T15:00:00Z\"\n))"
- language: php
code: "<?php\n$client = new \\ProcessOut\\ProcessOut(\n \"test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x\", \n \"key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB\");\n\n// The source could also be a token tok_fKK4btSG7wd13ZZaevzhMcuNbpjcu1Zy\n$transaction = $invoice->authorize(\"card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ\", array(\n // optional if you want us to auto capture for you\n \"auto_capture_at\" => \"2022-10-02T15:00:00Z\"\n));"
- language: go
code: "import \"github.com/processout/processout-go\"\n\nvar client = processout.New(\n \"test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x\", \n \"key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB\",\n)\n\n// The source could also be a token tok_fKK4btSG7wd13ZZaevzhMcuNbpjcu1Zy\ntr, _ := iv.Authorize(\"card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ\", InvoiceAuthorizeParameters{\n AutoCaptureAt: \"2022-10-02T15:00:00Z\",\n})"
samples-languages:
- node
- python
- ruby
- php
- go
tags:
- Invoices
/invoices/{invoice_id}/capture:
post:
summary: Capture an invoice
description: ''
operationId: capture-an-invoice
parameters:
- name: Idempotency-Key
in: header
description: Unique key to your request that will be used for idempotency
schema:
type: string
- name: invoice_id
in: path
description: The invoice ID generated by ProcessOut during the invoice creation
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
source:
type: string
description: Source used to capture the payment. Can be a card, a token or a gateway request.
invoice_detail_ids:
type: array
description: Array of invoice details created with the invoice to capture.<br>_Only supported on compatible payment providers_
items:
type: string
capture_amount:
type: string
description: Amount to capture partially the transaction
capture_statement_descriptor:
type: string
description: Some payment providers are supporting different statement descriptor for the capture. Use this field to send a different one. By default, the one sent during the authorization will be forwarded.
# --- truncated at 32 KB (179 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/processout/refs/heads/main/openapi/processout-invoices-api-openapi.yml