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. |
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. |
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. |
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. |
Shipping object
Field | Type | Description |
---|---|---|
amount | string | Amount charged for 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 |
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
}