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. 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
cancel_url	string	For APMs, this is the URL to return to the app after payment is canceled. 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 when the invoice was created.

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	string	Channel used by the device. 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

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

JSON object

{
    "invoice": {
        "id": "iv_JJNNzBnshKrvwDXZXImUimiZ2B5juY6m",
        "project_id": "proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S",
        "subscription_id": null,
        "customer_id": "cust_D5BDaQQ8XL4xoUfKRjpBQjoEIwMA6asA",
        "token_id": null,
        "details": [
            {
                "id": "iv_det_6iRqpN8Drk2ZxkUH18Ei1Jgv5Gg1bRuE",
                "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_rJ8iy3vhs8OgRfxsm8DR4Tr1g2a8BpMU",
        "name": "Amazing Product",
        "amount": "29",
        "currency": "EUR",
        "metadata": {
            "fruit": "banana"
        },
        "gateway_data": {},
        "exemption_reason_3ds2": null,
        "challenge_indicator": null,
        "sca_exemption_reason": null,
        "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_JJNNzBnshKrvwDXZXImUimiZ2B5juY6m",
        "created_at": "2023-04-24T09:17:13.370001883Z",
        "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": null,
        "tax": {
            "rate": "1",
            "amount": "10"
        },
        "payment_type": null
    },
    "success": true
}