Invoice objects are very important in the payment process. You must create an invoice before you can accept a payment, but you can also use it to store many other pieces of information about a purchase.

For example:

Shipping information
Details and availability of the items to be purchased
Sales tax

See the guide page about Creating an invoice for a full description of how it fits into the payment flow.

Invoice object

List of fields

📘
While the invoice object may seem to contain many parameters, only a handful are useful to merchants. Other may be used under specific scenarios as ProcessOut is fully transparent with the data it gathers. The following list contains most parameters that may be useful to merchants

Field	Type	Description
id	string readonly	String value that uniquely identifies this invoice.
name	string	Name of the invoice (often an internal ID code from the merchant’s systems). Maximum 80 characters long
amount	string	Amount to be paid.
currency	string	Currency for payment of the invoice, in ISO 4217 format (for example, `USD`). Must be a valid ISO 4217 currency code with 3 characters
initiation_type	string	Represent the initiation type of the transaction which can be Customer Initiated Transaction (`cit`) or Merchant Initiated Transaction (`mit`). Allowed values are:`cit` or `mit`
payment_intent	string	For Merchant Initiated Transactions: the type of payment flow that generated the transaction. Allowed values are:`one-off`, `recurring`, `recurring-standing-order`, `recurring-subscription`, `installment`, `unscheduled`, `unscheduled-delayed-charge`, `unscheduled-resubmission`, `unscheduled-no-show` or `unscheduled-reauthorization`.
metadata	object	Metadata related to the invoice, in the form of key-value pairs (string - string).
sca_exemption_reason	string	Optional reason for requesting SCA exemption (Note: This must also be supported by the PSP. Please contact us for more information.) Allowed values are:`low-value`, `trusted-beneficiary` or `transaction-risk-analysis`
challenge_indicator	string	Optional challenge indicator field when requesting 3DS2 (Note: This must also be supported by the PSP. Please contact us for more information.) Allowed values are:`no-preference`, `no-challenge-requested`, `challenge-requested`, `challenge-requested-mandate`, `no-challenge-requested-tra-performed`, `no-challenge-requested-data-share-only`, `no-challenge-requested-sca-performed`, `no-challenge-requested-whitelist-exemption`, `challenge-requested-whitelist-prompt` or `cb-scoring`
payment_type	string	Optional information about the payment type Allowed values are`moto` or `ecommerce`
sandbox	boolean readonly	Denotes whether or not this invoice was created in the sandbox testing environment.
statement_descriptor	string	Item that will be listed for this purchase on the customer’s bank statement. Defaults to invoice.name if not provided. Maximum 22 characters long, should only contain letters, numbers, spaces, dots and forward slashes
statement_descriptor_phone	string	Support phone number for this purchase on the customer’s bank statement.
statement_descriptor_city	string	City shown for this purchase on the customer’s bank statement.
statement_descriptor_company	string	Your company name to show on the customer’s bank statement.
statement_descriptor_url	string	Support URL for this purchase on the customer’s bank statement.
project_id (Expandable)	string readonly	Project that the invoice belongs to.
customer_id (Expandable)	string	Customer linked to the invoice (generally the one making the purchase). See Customers object
transaction_id (Expandable)	string readonly	Transaction generated when the invoice is authorized or captured. See Transaction object
token_id (Expandable)	string	Token that was used, or will be used, to capture the payment. If the invoice is linked to a customer (via the `customer` field) then this token must belong to them. See Tokens object
details	[]object	Details of the items or products that are being purchased. See Details object
risk	object	Risk assessment for the invoice. See Risk object
device	object	Information about the device (web, mobile, other) that was used to start the purchase. See Device object
external_fraud_tools	object	Information to forward to external fraud tools. See ExternalFraudTools object
shipping	object	Shipping information for the invoice. See Shipping object
return_url	string	For APMs, this is the URL to return to the app after payment is accepted. Must be a valid URL
webhook_url	string	Custom webhook URL for this purchase. Must be a valid URL
incremental	string readonly	Denotes whether or not you can apply incremental authorizations to this invoice.
tax	object	Tax information for the invoice. See tax object
unsupported_feature_bypass	object	Bypass payment provider unsupported features set in the transaction
created_at	datetime readonly	Date and time of when the invoice was created.
expires_at	datetime	Date and time of when the invoice will expire, when it will not be possible to initiate a new transaction on it.
payment_methods	[]object	Payment methods for Dynamic Checkout. Requires the `expand=payment_methods` query string parameter. See Payment method object

Details object

Field	Type	Description
id	string readonly	String value that uniquely identifies this invoice detail.
name	string	Name of the item or product, which represents an item on a receipt. Maximum 80 characters long
amount	string	Amount charged for this item or product.
tax_amount	string	Amount of taxes charged for this item or product.
type	string	Item or product type. Set this to anything suitable. Maximum 30 characters long
quantity	integer	Quantity of the item or product. Default value is 1.
unit	string	Unit of measure used for product quantity.
category	string	Category of the item or product. Can be `food`, `entertainment`, `home`, `appliance`, `bidding`, `gift`, `technology`, `media`, `communication`, `health`, `sport`, `tickets`, `personal-service`, `professional-service`, `clothing`, `travel`, `transport` or `other`.
reference	string	Reference of the item or product. Maximum 255 characters long
description	string	Description of the item or product. Maximum 255 characters long
brand	string	Brand of the item or product. Maximum 80 characters long
model	string	Model of the item or product. Maximum 80 characters long
discount_amount	string	Discount amount (when the discount is listed as a separate item on a receipt).
condition	string	Condition of the product. Can be `new`, `refurbished`, `used` or `other`.
marketplace_merchant	string	Marketplace merchant ID of the item or product.
marketplace_merchant_is_business	boolean	Denotes whether or not the marketplace merchant is a business.
marketplace_merchant_created_at	datetime	Date and time when the merchant was created.
visa_commodity_code	string	Visa specific commodity code used for the item. Please refer to Visa for list of codes.

Risk object

Field	Type	Description
score	string	Scoring of the invoice. No validation done on this field because it is used to forward risk information to compatible payment providers. Maximum 12 characters long
is_legit	boolean	Denotes whether or not the invoice is legitimate.
skip_gateway_rules	boolean	Flag to skip payment gateway fraud engine rules. (This is only available on certain compatible gateways. Contact us for more information.)

Device object

Field	Type	Description
id	string	ID of the device. This can be anything but would usually be a UUID generated by a third-party anti-fraud solution.
channel (deprecated)	string	Channel used by the device. Can be `web`, `ios`, `android` or `other`.
threeds_sdk	string	Three DS SDK which is used by the gateways. Can be `web`, `ios`, `android` or `other`.
platform	string	The device platform which is used for the transaction. Can be `web`, `ios`, `android` or `other`.
ip_address	string	IP address of the device. Must be a valid IP address

ExternalFraudTools object

Field	Type	Description
forter	raw json	Information for the Forter fraud prevention service.
signifyd	raw json	Information for the Signifyd fraud prevention service.
ravelin	raw json	Information for the Ravelin fraud prevention service.

Shipping object

Field	Type	Description
amount	string	Amount charged for shipping.
duty_amount	string	Amount charged for import/export duties related to shipping.
method	string	Delivery method. Can be `web`, `collect-at-shop`, `relay`, `travel-station`, `home`, `shipping`, `locker` or `other`.
provider	string	Delivery provider. Maximum 32 characters long
delay	string	Shipment delay. Can be `express`, `priority`, `standard` or `other`.
address1	string	First line of the delivery address. Maximum 255 characters long
address2	string	Second line of the delivery address. Maximum 255 characters long
state	string	State or county of the delivery address. Maximum 80 characters long
city	string	City of the delivery address. Maximum 80 characters long
country_code	string	Country code (`US`, `FR`…) of the delivery address. Must be a valid ISO 3166 country code with 2 characters
zip	string	ZIP code of the delivery address. Maximum 16 characters long
from_zip	string	ZIP code of the address from which delivery is shipped. Maximum 16 characters long
phone	object	Phone number of the shipment recipient.
expects_shipping_at	datetime	Expected date of delivery.
relay_store_name	string	Name of the store that the order must be collected from. Maximum 100 characters long

Phone object

Field	Type	Description
number	string	Phone number without the dialing code. Maximum 14 characters long
dialing_code	string	International dialing code (Note: “+” will be treated as “00”)

Tax object

Field	Type	Description
amount	string	Amount is zero or a positive number representing the tax included in the amount.
rate	string	Rate is a percentage (0 to 100) representing the rate of tax included in the amount.

Unsupported feature bypass object

Field	Type	Description
incremental_authorization	bool	Ignore incremental authorization requests on PSP that doesn't support it

Payment method object

Field	Type	Description
type	string	Type of payment method. Can be `applepay`, `googlepay`, `apm`,`apm_customer_token`, `card` or `card_customer_token`
flow	string	Optional flow of the payment method. Can be `express`
display	object	Display information of the payment method. See Display object
applepay	object	Apple Pay payment method information. See Apple Pay object
googlepay	object	Google Pay payment method information. See Google Pay object
apm	object	APM payment method information. See APM object
apm_customer_token	object	APM's customer token payment method information. See APM customer token object
card	object	Card payment method information. See Card object
card_customer_token	object	Card's customer token payment method information. See Card customer token object

Display object

Field	Type	Description
name	string	Name of the payment method
logo	object	Logo urls of the payment method
brand_color	object	Hexadecimal color codes of the payment method

Apple Pay object

These attributes are documented in the Apple Pay website

Field	Type	Description
merchant_id	string	Merchant identifier
country_code	string	Merchant country code Must be a valid ISO 3166 country code with 2 characters
supported_networks	[]string	Card networks supported. e.g. `american express`. These values need to be mapped to the corresponding Apple Pay values
merchant_capabilities	[]string	Payment processing capabilities. Can be `supports3DS`, `supportsCredit`, `supportsDebit` and `supportsEMV`. These values need to be mapped to the corresponding Apple Pay values

Google Pay object

These attributes are documented in the Google Pay website

Field	Type	Description
allowed_auth_methods	[]string	Card transaction authentication methods. Can be `PAN_ONLY`and/or `CRYPTOGRAM_3DS`
allowed_card_networks	[]string	Card networks supported
allow_prepaid_cards	boolean	Whether prepaid cards are supported
allow_credit_cards	boolean	Whether credit card are supported
gateway	string	Gateway identifier issued by Google. Always `processout`
gateway_merchant_id	string	Gateway account identifier. Always the ProcessOut project identifier
country_code	string	Country where the transaction is processed. Required for transactions in European Economic Area (EEA). Must be a valid ISO 3166 country code with 2 characters

APM object

Field	Type	Description
gateway_configuration_id	string	Gateway configuration that the payment method is linked to. Relevant to the native flow
gateway_name	string	Gateway configuration's gateway name
gateway_logo_url	string	Gateway configuration's gateway logo url
redirect_url	string	Optional url used to redirect the customer to a third-party payment provider website to complete their payment. Relevant to the redirect flow
saving_allowed	boolean	Whether the customer can be asked if they wish to save the payment method for future use

APM customer token object

Field	Type	Description
customer_token_id	string	The customer's token that the alternative payment method is linked to
gateway_configuration_id	string	Gateway configuration that the payment method is linked to. Relevant to the native flow
gateway_name	string	Gateway configuration's gateway name
gateway_logo_url	string	Gateway configuration's gateway logo url
redirect_url	string	Optional url used to redirect the customer to a third-party payment provider website to complete their payment. Relevant to the redirect flow

Card object

Field	Type	Description
billing_address	object	Billing address options
cvc_required	boolean	CVC is required at card tokenization
cardholder_name_required	boolean	Cardholder's name is required at card tokenization
saving_allowed	boolean	Whether the customer can be asked if they wish to save the card for future use
restrict_to_schemes	[]string	Whether tokenization should be restricted to specific card schemes. e.g. visa, mastercard, amex, etc. Can't be set with `restrict_to_iins`.
restrict_to_iins	[]string	Whether tokenization should be restricted to specific issuer identification numbers (IINs). e.g. 411111, 550000, etc. Can't be set with `restrict_to_schemes`.
scheme_selection_enabled	boolean	Whether scheme selection should be displayed when multiple schemes (co-scheme) are available
scheme_selection_default_order	[]string	When scheme selection is enabled and the card supports multiple schemes, the first scheme in this list that is available should be selected by default when rendering the scheme selector. e.g. "carte bancaire", "visa" defaults to "carte bancaire

Card customer token object

Field	Type	Description
customer_token_id	string	The customer's token that the card is linked to

JSON object

{
    "invoice": {
        "id": "iv_MyNUnrEwNf7mrXZO1x6x8eeCoTWC8OQG",
        "project_id": "proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S",
        "subscription_id": null,
        "customer_id": "cust_MFW0Z4jtoXLfADjPKlVRl5LxWkCTUgRw",
        "token_id": null,
        "details": [
            {
                "id": "iv_det_M2LqRkMXxkTSu4CWTMY0X4QKrzz2Urbu",
                "name": "iPhone 14 Pro",
                "type": "Smartphone",
                "amount": "1000",
                "quantity": 1,
                "reference": "12221341242",
                "description": "iPhone 11 Pro 256Gb Red blablabla",
                "brand": "Apple",
                "model": "14 Pro",
                "discount_amount": "0",
                "condition": "new",
                "marketplace_merchant": null,
                "marketplace_merchant_is_business": null,
                "marketplace_merchant_created_at": null,
                "category": "technology",
                "metadata": {}
            }
        ],
        "transaction_id": "tr_Cln3zmZ31m5Crcgz5sfggomIiMm3Mmbm",
        "name": "Amazing Product",
        "order_id": "123456",
        "amount": "29",
        "currency": "EUR",
        "metadata": {
            "fruit": "banana"
        },
        "gateway_data": {},
        "exemption_reason_3ds2": "",
        "challenge_indicator": "",
        "sca_exemption_reason": "",
        "statement_descriptor": "My Company",
        "merchant_initiator_type": null,
        "initiation_type": "MIT",
        "payment_intent": "recurring",
        "require_backend_capture": null,
        "card_verification": null,
        "return_url": "https://mycompany.com/return-url",
        "cancel_url": null,
        "webhook_url": "https://mycompany.com/webhook",
        "sandbox": true,
        "url": "https://checkout.processout.com/test-proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S/iv_MyNUnrEwNf7mrXZO1x6x8eeCoTWC8OQG",
        "created_at": "2023-04-21T17:57:22.807583563Z",
        "expires_at": null,
        "risk": {
            "score": "100",
            "is_legit": true,
            "skip_gateway_rules": false
        },
        "device": {
            "id": "112233445566",
            "channel": "ios",
            "ip_address": "1.1.1.1"
        },
        "shipping": {
            "amount": "12",
            "method": "home",
            "provider": "DHL",
            "delay": "express",
            "address1": "133 Rue Lamarck",
            "address2": "CEDEX 1",
            "city": "Paris",
            "state": "Ile De France",
            "country_code": "FR",
            "zip": "75018",
            "phone": {
            		"number": "684758495",
            		"dialing_code": "0033"
        		},
            "expects_shipping_at": "2023-04-21T17:52:47.828402061Z",
            "relay_store_name": "none"
        },
        "incremental": false,
        "tax": {
            "rate": "1",
            "amount": "10"
        },
        "payment_type": null,
        "payment_methods": [
            {
                "type": "applepay",
                "flow": "express",
                "applepay": {
                    "merchant_id": "merchant.mycompany.processout.com",
                    "country_code": "GB",
                    "supported_networks": [
                        "american express",
                        "visa"
                    ],
                    "merchant_capabilities": [
                        "supports3DS",
                        "supportsCredit",
                        "supportsDebit",
                        "supportsEMV"
                    ]
                }
            },
            {
                "type": "googlepay",
                "flow": "express",
                "googlepay": {
                    "allowed_auth_methods": [
                        "PAN_ONLY",
                        "CRYPTOGRAM_3DS"
                    ],
                    "allowed_card_networks": [
                        "AMEX",
                        "DISCOVER",
                        "JCB",
                        "MASTERCARD",
                        "VISA"
                    ],
                    "allow_prepaid_cards": true,
                    "allow_credit_cards": true,
                    "gateway": "processout",
                    "gateway_merchant_id": "proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S",
                  	"country_code": "GB"
                }
            },
            {
                "type": "apm",
                "display": {
                    "name": "Everypay",
                    "logo": {
                        "light_url": {
                            "vector": "https://js.processout.com/images/payment-methods/square/everypay.svg",
                            "raster": "https://js.processout.com/images/payment-methods/square/everypay-m@4x.png"
                        },
                        "dark_url": {
                            "vector": "https://js.processout.com/images/payment-methods/square/everypay.svg",
                            "raster": "https://js.processout.com/images/payment-methods/square/everypay-m@4x.png"
                        }
                    },
                    "brand_color": {
                        "light": "0x000000FF",
                        "dark": "0xFFFFFFFF"
                    }
                },
                "apm": {
                    "gateway_configuration_id": "gway_conf_yt57esj68rj0ic4egt8bkjp4iin0dwpm.everypay",
                    "redirect_url": "https://checkout.processout.com/proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S/iv_MyNUnrEwNf7mrXZO1x6x8eeCoTWC8OQG/redirect/gway_conf_yt57esj68rj0ic4egt8bkjp4iin0dwpm.everypay",
                  	"saving_allowed": true
                }
            },
            {
                "type": "card",
                "display": {
                    "name": "Card",
                    "logo": {
                        "light_url": {
                            "vector": "https://js.processout.com/images/payment-methods/square/card.svg",
                            "raster": "https://js.processout.com/images/payment-methods/square/card-m@4x.png"
                        },
                        "dark_url": {
                            "vector": "https://js.processout.com/images/payment-methods/square/card.svg",
                            "raster": "https://js.processout.com/images/payment-methods/square/card-m@4x.png"
                        }
                    },
                    "brand_color": {
                        "light": "0x000000FF",
                        "dark": "0xFFFFFFFF"
                    }
                },
                "card": {
                    "cvc_required": true,
                    "cardholder_name_required": true,
                    "scheme_selection_allowed": true,
                    "billing_address": {
                        "collection_mode": "full",
                        "restrict_to_country_codes": [
                            "GB"
                        ]
                    },
                    "saving_allowed": false
                }
            }
        ]
    },
    "success": true
}

What’s Next

What’s Next