Improve payment request data quality

Last updated: December 11, 2024

When you create a payment request, you must include all required API fields for the request to be valid.

However, including certain optional payment and authentication fields can help better identify fraudulent transactions and reduce false declines.

Providing additional authentication data helps identify recent account or password changes, which may indicate increased fraud risk.

If your payment request has 3ds.enabled set to true, we recommend that you always also include the following fields:

3ds.account_info.account_age
3ds.account_info.account_change
3ds.account_info.account_password_change


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54",
5    "billing_address": {
6      "address_line1": "123 High St.",
7      "address_line2": "Flat 456",
8      "city": "Leeds",
9      "state": "GB",
10      "zip": "LS1 1BA",
11      "country": "GB"
12    },
13    "account_holder": {
14      "type": "individual",
15      "first_name": "Toby",
16      "last_name": "Arden"
17    }
18  },
19  "amount": 30,
20  "currency": "GBP",
21  "payment_type": "Recurring",
22  "reference": "ORD-5023-4E89",
23  "description": "Set of 3 masks",
24  "capture": true,
25  "capture_on": "2024-09-10T10:11:12Z",
26  "customer": {
27    "id": "cus_udst2tfldj6upmye2reztkmm4i",
28    "email": "[email protected]",
29    "name": "Toby Arden",
30    "phone": {
31      "country_code": "+44",
32      "number": "496 0999"
33    }
34  },
35  "billing_descriptor": {
36    "name": "Withdrawal",
37    "city": "Leeds"
38  },
39  "shipping": {
40    "address": {
41      "address_line1": "Checkout.com",
42      "address_line2": "Flat 456",
43      "city": "Leeds",
44      "state": "GB",
45      "zip": "LS1 1BA",
46      "country": "GB"
47    },
48    "phone": {
49      "country_code": "+44",
50      "number": "496 0999"
51    }
52  },
53  "3ds": {
54    "enabled": true,
55    "attempt_n3d": true,
56    "eci": "05",
57    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
58    "xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
59    "version": "2.0.1",
60    "account_info": {
61      "account_age": "more_than_sixty_days",
62      "account_change": "2024-07-10T10:11:12Z",
63      "account_password_change": "2024-01-15T10:11:12Z"
64    }
65  },
66  "previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
67  "risk": {
68    "enabled": false
69  },
70  "success_url": "https://example.com/payments/success",
71  "failure_url": "https://example.com/payments/fail",
72  "payment_ip": "90.197.169.245",
73  "recipient": {
74    "dob": "1985-05-15",
75    "account_number": "5555554444",
76    "zip": "LS1 1BA",
77    "last_name": "Arden"
78  },
79  "metadata": {
80    "coupon_code": "NY2024",
81    "partner_id": 123989
82  },
83  "segment": {
84    "brand": "Acme Corporation",
85    "business_category": "Inward Payment",
86    "market": "UK"
87  }
88}

Providing additional customer data for cardholder-initiated transactions (CITs) may improve your acceptance rate. It also helps issuer and Checkout.com fraud prevention systems verify the transaction's legitimacy, and reduces the likelihood of false declines.

Information

We recommend integrating with our Risk SDK for CITs. The SDK captures device data that helps identify potentially fraudulent transactions.

If your payment request has source.type set to one of the following:

ach
card
customer
id
network_token
token

Then we recommend also including the following fields:

source.billing_address
source.account_holder.first_name
source.account_holder.last_name
customer.name
customer.email
payment_ip – if payment_type is not set to MOTO
shipping.address – if you're shipping goods


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54",
5    "billing_address": {
6      "address_line1": "123 High St.",
7      "address_line2": "Flat 456",
8      "city": "Leeds",
9      "state": "GB",
10      "zip": "LS1 1BA",
11      "country": "GB"
12    },
13    "account_holder": {
14      "type": "individual",
15      "first_name": "Toby",
16      "last_name": "Arden"
17    }
18  },
19  "amount": 30,
20  "currency": "GBP",
21  "payment_type": "Recurring",
22  "reference": "ORD-5023-4E89",
23  "description": "Set of 3 masks",
24  "capture": true,
25  "capture_on": "2024-09-10T10:11:12Z",
26  "customer": {
27    "id": "cus_udst2tfldj6upmye2reztkmm4i",
28    "email": "[email protected]",
29    "name": "Toby Arden",
30    "phone": {
31      "country_code": "+44",
32      "number": "496 0999"
33    }
34  },
35  "billing_descriptor": {
36    "name": "Withdrawal",
37    "city": "Leeds"
38  },
39  "shipping": {
40    "address": {
41      "address_line1": "Checkout.com",
42      "address_line2": "Flat 456",
43      "city": "Leeds",
44      "state": "GB",
45      "zip": "LS1 1BA",
46      "country": "GB"
47    },
48    "phone": {
49      "country_code": "+44",
50      "number": "496 0999"
51    }
52  },
53  "3ds": {
54    "enabled": false
55  },
56  "previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
57  "risk": {
58    "enabled": false
59  },
60  "success_url": "https://example.com/payments/success",
61  "failure_url": "https://example.com/payments/fail",
62  "payment_ip": "90.197.169.245",
63  "recipient": {
64    "dob": "1985-05-15",
65    "account_number": "5555554444",
66    "zip": "LS1 1BA",
67    "last_name": "Arden"
68  },
69  "metadata": {
70    "coupon_code": "NY2024",
71    "partner_id": 123989
72  },
73  "segment": {
74    "brand": "Acme Corporation",
75    "business_category": "Inward Payment",
76    "market": "UK"
77  }
78}

Providing additional customer data for Mail Order/Telephone Order (MOTO) transactions helps issuer and Checkout.com fraud prevention systems verify the transaction's legitimacy. This can reduce the likelihood of false declines.

If your MOTO payment request has source.type set to one of the following:

ach
card
customer
id
network_token
token

Then we recommend also including the following fields:

customer.phone
shipping.address


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54",
5    "billing_address": {
6      "address_line1": "123 High St.",
7      "address_line2": "Flat 456",
8      "city": "Leeds",
9      "state": "GB",
10      "zip": "LS1 1BA",
11      "country": "GB"
12    }
13  },
14  "amount": 30,
15  "currency": "GBP",
16  "payment_type": "Recurring",
17  "reference": "ORD-5023-4E89",
18  "description": "Set of 3 masks",
19  "capture": true,
20  "capture_on": "2024-09-10T10:11:12Z",
21  "customer": {
22    "id": "cus_udst2tfldj6upmye2reztkmm4i",
23    "email": "[email protected]",
24    "name": "Toby Arden",
25    "phone": {
26      "country_code": "+44",
27      "number": "496 0999"
28    }
29  },
30  "billing_descriptor": {
31    "name": "Withdrawal",
32    "city": "Leeds"
33  },
34  "shipping": {
35    "address": {
36      "address_line1": "Checkout.com",
37      "address_line2": "Flat 456",
38      "city": "Leeds",
39      "state": "GB",
40      "zip": "LS1 1BA",
41      "country": "GB"
42    },
43    "phone": {
44      "country_code": "+44",
45      "number": "496 0999"
46    }
47  },
48  "3ds": {
49    "enabled": false
50  },
51  "previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
52  "risk": {
53    "enabled": false
54  },
55  "success_url": "https://example.com/payments/success",
56  "failure_url": "https://example.com/payments/fail",
57  "payment_ip": "90.197.169.245",
58  "recipient": {
59    "dob": "1985-05-15",
60    "account_number": "5555554444",
61    "zip": "LS1 1BA",
62    "last_name": "Arden"
63  },
64  "metadata": {
65    "coupon_code": "NY2024",
66    "partner_id": 123989
67  },
68  "segment": {
69    "brand": "Acme Corporation",
70    "business_category": "Inward Payment",
71    "market": "UK"
72  }
73}

Improve payment request data quality

3D Secure authenticated payments

Cardholder-initiated transactions

Information

MOTO transactions