Full API reference
Introduction
Shift4 API is a REST-based API that allows fast and easy integration. We use HTTP for transport and return all responses encoded as JSON.
To simplify integration and testing, each account has two modes: test mode and live mode. Each mode has its own set of public and secret keys. We guarantee that test-mode data never reach real customers and never costs you money.
API ENDPOINT
https://api.shift4.com
Authentication
Shift4 API uses "HTTP Basic authentication" for authentication. All requests to our API must be authenticated, and all requests have to be made over HTTPS.
To authenticate, you need to provide your "API Secret Key" as a username and leave the password blank. Once logged in, you can find your API keys in your account settings. It's critical to keep your "API Secret Key" secure because it allows others to perform privileged operations on your behalf.
EXAMPLE REQUEST
curl https://api.shift4.com/charges \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
Note: adding colon after API key will prevent curl from asking for password
Errors
Shift4 API uses HTTP codes to indicate the outcome of an API call. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error on your end (something is wrong with your request), and codes in the 5xx range indicate an error on our end.
If request fails an error object is returned instead of a normal response.
HTTP Status codes
200 OK - Successful request
400 Bad Request - Request has invalid data or is missing a required field
401 Unauthorized - Provided API key is missing or invalid
402 Payment failed - Request was valid but card processing has failed
404 Not Found - Requested object was not found
429 Too Many Requests - Requests hit the API too quickly
500, 502, 503, 504 Server error - Something went wrong on our side
Error object
Attributes
type | string
Type of error. Possible values are:
invalid_request
- Request has invalid or missing parameterscard_error
- Card processing has failedgateway_error
- Something went wrong on our siderate_limit_error
- Requests hit the API too quickly
code | string
Additional details about the card error (only present when type=card_error
).
Possible values are:
amount_too_high
- The specified amount is greater than the maximum amount allowed.amount_too_low
- The specified amount is lower than the minimum amount allowed.invalid_number
- The card number is not a valid one.invalid_number
- Your request was in test mode, but used a non test card. For a list of valid test cards, visit our doc site.invalid_expiry_month
- The card's expiration month is invalid.invalid_expiry_year
- The card's expiration year is invalid.invalid_cvc
- Your card's security code is invalid.incorrect_cvc
- The card's security code failed verification.invalid_account
- Account details failed verification.incorrect_zip
- The card's zip code failed verification.incorrect_address
- The card's address failed verification.expired_card
- The card has expired.insufficient_funds
- The charge amount exceeds the available fund or the card's credit limit.lost_or_stolen
- The card is marked as lost or stolen.suspected_fraud
- The charge is suspected to be fraudulent.card_declined
- The card was declined for another reason.brand_not_supported
- The card brand is not supported.currency_not_supported
- Your account is not configured to process given currency. Please contact [email protected] for details.processing_error
- An error occurred while processing the card.expired_token
- The token has expired.authentication_required
- The charge requires authentication.blocked
- Transaction was blocked by rules engine.call_issuer
- The card was declined for an unknown reason. Contact the card issuer for more information.limit_exceeded
- You have exceeded bank's refund limit.do_not_try_again
- The card was declined and should not be retried.payment_method_declined
- The payment method was declined
message | string
A human-readable message that describes the reason for this error. Note that the content of this message is not intended to be parsed, and the format of this message can change at any moment.
issuerDeclineCode | string
Error code supplied by the card issuer. Only present when the request resulted in a declined charge, and that charge was declined by the card issuer.
chargeId | string
Identifier of the charge object associated with this error. Only present when the request resulted in a declined charge.
blacklistRuleId | string
Identifier of the blacklist rule object that matched this request. Only present when the request was blocked by the blacklist.
creditId | string
Identifier of the credit object associated with this error. Only present when request resulted in the declined credit.
EXAMPLE ERROR RESPONSE
{
"error" : {
"type" : "card_error",
"code" : "invalid_number",
"message" : "The card number is not a valid one."
}
}
Metadata
The metadata
attribute on most updatable objects can be used to store custom pairs of key-value data.
This is useful for storing extra structured information about a specific object. For example, you could save a user login along with a customer object that represents that user.
Each key within a given metadata object must be unique. Each key and value can hold up to 255 characters.
EXAMPLE REQUEST
{
"email" : "[email protected]",
"metadata" : {
"key1" : "value1",
"key2" : "value2"
}
}
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"metadata" : {
"key1" : "value1",
"key2" : "value2"
}
}
Charges
Charge represents a payment made with a credit or a debit card.
Charge object
Attributes
id | string
created | timestamp
objectType | string (value is always "charge")
amount | integer
Charge amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
The charge currency represented as a three-letter ISO currency code.
type | string
description | string
card | card object
A card that was used to create this charge.
status | string
The status of the payment process. It can be one of the following:
successful
- payment was completed successfullypending
- payment is being processed, see theflow
for details. Possible for payment method charges only.failed
- payment failed
paymentMethod | payment method object
Payment Method that was used to create this charge.
clientObjectId | string
Can be used with 'shift4.js' to check Payment Method charge status and required actions.
flow | object
Only applicable for payment method charges Specifies what actions (if any) must be taken to complete the payment process. Can contain the following attributes:
nextAction (string) - one of the following options:
redirect
- the client should be redirected to the URL specified in theflow.redirect.redirectUrl
wait
- payment is being processed, wait forflow.nextAction
change.none
returnUrl (string) - specifies where the user will be redirected after the payment has been completed
redirect (object) - present when
nextAction='redirect'
redirectUrl (string) - URL to which user should be redirected to complete the payment.
customerId | string
Identifier of the customer who owns this charge or null
if this charge is unrelated to any customer.
subscriptionId | string
Identifier of the subscription associated with this charge or null
if no subscription is associated with this charge.
captured | boolean
refunded | boolean
refunds | list of refund objects
List of refunds issued for this charge.
disputed | boolean
dispute | dispute object
Details about the dispute over this charge.
fraudDetails | object
Details about the fraud check conducted on this charge. Can contain the following attributes:
status (string) - can be one of the following:
safe
,suspicious
orfraudulent
score (integer) - the percentage chance that the charge is fraudulent
arn | string
Acquirer Reference Number
shipping | object
Shipping details. Can contain the following attributes:
name (string) - name of the recipient
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
phone (string) - phone of the recipient
billing | object
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
email (string) - email of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a wo-letter ISO country code
phone (string) - phone of billed person or company
vat (string) - tax identification number
threeDSecureInfo | object
Additional data present if card used to create this charge was verified with 3D Secure. Can contain following attributes:
amount (integer) - amount in minor units that was used in 3D Secure
currency (string) - currency that was used in 3D Secure (represented as a three-letter ISO currency code)
enrolled (boolean) - information on whether the card used to create this charge supports 3D Secure
liabilityShift (string) - can have one of the following values:
null
- 3D Secure was not started or is in progresssuccessful
- 3D Secure was completed successfullyfailed
- 3D Secure is supported, but was not completed successfullynot_possible
- 3D Secure is not supported
authenticationFlow (string) - can have one of the following values:
frictionless
- Issuer authenticated the customer via the frictionless flow.challenge
- Issuer authenticated the customer by showing a challenge window.
avsCheck | object
Additional data present if address was verified. Can contain following attributes
result (string) - can have one of the following values:
full_match
- All address elements matchedpartial_match
- Some address elements matchedno_match
- No address element matchednot_provided
- Address not providedunavailable
- Address verification service was unavailable
aniCheck | object
Contains field result that informs about the outcome of the ANI check. Possible values: full_match
, partial_match
, no_match
, not_verified
, not_supported
.
merchantAccountId | string
Identifier of the merchant account that was used to create this charge.
metadata | metadata object
failureCode | string
Error code that describes why the charge has failed. Only present in failed charges. For the list of possible values, see the code
attribute in the error object.
failureMessage | string
A human-readable message that describes why the charge has failed. Only present in failed charges.
failureIssuerDeclineCode | string
Error code supplied by the card issuer. Only present in failed charges.
EXAMPLE OBJECT
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"customerId" : null,
"captured" : true,
"refunded" : false,
"refunds" : [],
"disputed" : false,
"metadata" : {}
}
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"customerId" : null,
"captured" : true,
"refunded" : false,
"refunds" : [],
"disputed" : false,
"metadata" : {},
"splits": {
"id": "spl_YUsnOoJZYap3PWwi6ByzbUYe",
"created" : 1415810800,
"objectType" : "charge_split",
"charge" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"type": "tip",
"amount" : 100,
"currency" : "USD",
"merchant": "mrc_SzA23wroCbvstqHVFYup007A"
}
}
Create a new Charge
Creates a new charge object.
Capturing a charge object (either at creation or at the later stage) will result in the charge of provided credit or debit card.
If you are in test mode, the provided credit or debit card won't actually be charged, but everything else will work the same as in live mode.
Arguments
amount | integer, required
Charge amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string, required
Charge currency represented as a three-letter ISO currency code
type | string, optional
Possible values are: first_recurring
, subsequent_recurring
, merchant_initiated
, customer_initiated
.
description | string, optional
customerId | string, optional (either customerId or card is required)
Identifier of the customer that will be associated with this charge. This field is required if the charge is being created with the customer's existing card. If specified, the successful charge created with a new card will add that card to the customer's cards and be set as customer's default card.
card | card token, card details or card identifier, optional (either customerId, card or paymentMethod is required)
Can be one of the following:
card token (for example, obtained from Components)
card details (same as in the card create request)
card identifier (must be an existing card that is associated with the customer-specified in
customerId
field)
If neither card nor payment method is provided, the customer's defaults will be used.
paymentMethod | payment method details or identifier, optional (either customerId, card or paymentMethod is required)
It can be one of the following:
payment method details (same as in payment method create request)
payment method identifier (must be an existing payment method that is associated with customer specified in
customerId
field)
If neither card nor payment method is provided, then the customer's defaults will be used.
flow | details specific to the payment method charge. Specifies payment process details.
returnUrl (required for paymentMethod charge) - URL to which the user will be redirected after processing payment on an external site. For convenience query parameter clientObjectId will be added, which can be afterwards used to check the charge status with
shift4.js
.
captured | boolean, optional (default is true)
Whether this charge should be immediately captured. When set to false charge is only authorized (or pre-authorized) and needs to be captured later.
shipping | object, optional
Shipping details. Can contain the following attributes:
name (string) - name of the recipient
address (object) - address object, can contain following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as two-letter ISO country code
phone (string) - phone of the recipient, eg. +12345678901
billing | object, optional, cannot be used together with paymentMethod
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
phone (string) - phone of billed person or company, eg. +12345678901
vat (string) - tax identification number
threeDSecure | object, optional
3D Secure options. It can contain the following attributes:
requireAttempt (boolean, default is false) - the charge will fail when the 3D Secure verification was not attempted
requireEnrolledCard (boolean, default is false) - the charge will fail if the card doesn't support 3D Secure (is not enrolled for 3D Secure verification)
requireSuccessfulLiabilityShiftForEnrolledCard (boolean, default is true) - the charge will fail when the card supports the 3D Secure verification, but that verification was not successful (i.e. customer cancelled the verification or provided invalid information in the 3D Secure popup)
external (object, optional) - used with an external 3DS service and can contain the following attributes:
version (string, required) - with one of following values: 2.1.0 and 2.2.0
eci (string, required) - Electronic Commerce Indicator e.g., 05
authenticationValue (string, optional) - other names: CAVV, AAV, UCAF
dsTransactionId (string, required for 3DS 2) - dsTransID received in ARes
acsTransactionId (string, required for 3DS 2) - acsTransID received in ARes
status (string, required) - can have one of the following values: Y, N, A, U, R, E
merchantAccountId | string, optional
Identifier of the merchant account that will be used to create this charge.
splits | list of split requests
Allows to transfer part of a charge amount to the given merchant. The amount of splits cannot be greater than 75% of that charge amount. Only one split is allowed. Request object must have the following attributes:
type (string, required) - split type, possible value:
tip
merchant (string, required) - merchant identifier to whom the money will be transferred, must be platform
amount (integer, required) - amount that will be transferred, must be positive
metadata | metadata object, optional
recipient | object, required
Funds recipient details. Can contain the following attributes:
firstName (string, required) - recipient's first name
lastName (string, required) - recipient's last name
accountNumber (string, required) - id representing the account being topped up in merchant's system
dateOfBirth (object, optional) - sender's date of birth (in YYYY-MM-DD format)
address (object, required) - address object, can contain following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as two-letter ISO country code
sender | object, required only if sender is different from the recipient
Funds sender details. Can contain the following attributes:
firstName (string, required) - sender's first name
lastName (string, required) - sender's last name
dateOfBirth (object, required) - sender's date of birth (in YYYY-MM-DD format)
referenceNumber (string, required) - id representing sender's account in merchant's system
source (string, required) - source of funds, possible values are:
debit_card
,credit_card
,prepaid_card
address (object, required) - address object, can contain following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as two-letter ISO country code
Result
Successful request returns a charge object that represents the created charge.
DEFINITION
POST https://api.shift4.com/charges
EXAMPLE REQUEST
curl https://api.shift4.com/charges \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=USD" \
-d "customerId=cust_AoR0wvgntQWRUYMdZNLYMz5R" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
-d "description=Example charge"
curl https://api.shift4.com/charges \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=USD" \
-d "customerId=cust_AoR0wvgntQWRUYMdZNLYMz5R" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
-d "description=Example charge"
-d "recipient.firstName=Albert" \
-d "recipient.lastName=Morrison" \
-d "recipient.dateOfBirth=1991-05-16" \
-d "recipient.accountNumber=w100203011" \
-d "recipient.address.line1=3254 Hiney Road" \
-d "recipient.address.line2=" \
-d "recipient.address.country=US" \
-d "recipient.address.city=Las Vegas" \
-d "recipient.address.state=NV" \
-d "sender.firstName=Ellia" \
-d "sender.lastName=Brooks" \
-d "sender.referenceNumber=u_1123541" \
-d "sender.dateOfBirth=2000-09-29" \
-d "sender.source=credit_card" \
-d "sender.address.line1=3846 Deer Ridge Drive" \
-d "sender.address.line2=2nd floor" \
-d "sender.address.country=US" \
-d "sender.address.city=Freehold" \
-d "sender.address.state=NJ"
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2027",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"captured" : true,
"refunded" : false,
"disputed" : false
}
{
"id": "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created": 1415810511,
"objectType": "charge",
"amount": 499,
"currency": "USD",
"description": "Example charge",
"card": {
"id": "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created": 1415810511,
"objectType": "card",
"first6": "424242",
"last4": "4242",
"fingerprint": "e3d8suyIDgFg3pE7",
"expMonth": "11",
"expYear": "2027",
"cardholderName": "John Doe",
"customerId": "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand": "Visa",
"type": "Credit Card",
"issuer": "Card Issuer Name",
"country": "CH"
},
"customerId": "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"captured": true,
"refunded": false,
"disputed": false,
"splits": {
"id": "spl_YUsnOoJZYap3PWwi6ByzbUYe",
"created": 1415810800,
"objectType": "charge_split",
"charge": "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"type": "tip",
"amount": 100,
"currency": "USD",
"merchant": "mrc_SzA23wroCbvstqHVFYup007A"
}
}
Retrieve an existing Charge
Retrieves an existing charge object.
Arguments
CHARGE_ID | string, required
Identifier of the the charge object that should be retrieved.
Result
Successful request returns a charge object.
DEFINITION
GET https://api.shift4.com/charges/{CHARGE_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false,
}
Update an existing Charge
Update an existing charge object.
Any not provided parameter will be left unchanged.
Arguments
CHARGE_ID | string, required
Identifier of charge object that should be updated.
customerId | string, optional
Identifier of customer that will be associated with this charge. Updating this field is only possible for the charge that is not assigned to any customer. Assigning a successful charge to the customer will result in adding the card used to create that charge to the customer's cards. The card will be set as the customer's default card.
description | string, optional
shipping | object, optional
Shipping details. Can contain the following attributes:
name (string) - name of the recipient
address (object) - address object, can contain following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as two-letter ISO country code
phone (string) - phone of the recipient, eg. +12345678901
billing | object, optional, cannot be used together with paymentMethod
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
phone (string) - phone of billed person or company, eg. +12345678901
vat (string) - tax identification number
fraudDetails | object, optional
Fraud details. It contains the attribute:
status (string) - can be one of the following:
safe
,suspicious
,fraudulent
,in_progress
orunknown
metadata | metadata object, optional
Result
A successful request returns a charge object that was updated.
DEFINITION
POST https://api.shift4.com/charges/{CHARGE_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "description=New description"
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "New description",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
}
Capture a Charge
Capture an existing charge that was created with the captured=false
attribute. This is the second part of two-step payment flow.
Arguments
CHARGE_ID | string, required
Identifier of the charge object that should be captured.
Result
A successful request returns a charge object that was captured.
DEFINITION
POST https://api.shift4.com/charges/{CHARGE_ID}/capture
EXAMPLE REQUEST
curl https://api.shift4.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q/capture \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X POST
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
}
List Charges
List charge objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
customerId | string, optional (either customerId or card is required)
Result
A successful request returns a list of charge objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/charges
EXAMPLE REQUEST
curl "https://api.shift4.com/charges?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
{ ... },
{ ... }
],
"hasMore" : true
}
Dispute object
Attributes
objectType | string (value is always "dispute").
created | timestamp
updated | timestamp
amount | integer
Dispute amount in minor units of a given currency. For example, 10€ is represented as "1000", and 10¥ is represented as "10".
currency | string
Dispute currency represented as a three-letter ISO currency code.
status | string
It can have one of the following values:
RETRIEVAL_REQUEST_NEW
RETRIEVAL_REQUEST_REPRESENTED
CHARGEBACK_NEW
CHARGEBACK_REPRESENTED_SUCCESSFULLY
CHARGEBACK_REPRESENTED_UNSUCCESSFULLY
reason | string
It can have one of the following values:
FRAUDULENT
UNRECOGNIZED
DUPLICATE
SUBSCRIPTION_CANCELED
PRODUCT_NOT_RECEIVED
PRODUCT_UNACCEPTABLE
CREDIT_NOT_PROCESSED
GENERAL
acceptedAsLost | boolean
EXAMPLE OBJECT
{
"objectType" : "dispute",
"created" : 1415896911,
"updated" : 1415896911,
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"amount" : 499,
"currency" : "USD",
"acceptedAsLost" : false
}
Charge Splits
Charge split represents transfer of a part of the charge amount to the given merchant.
Charge split object
Attributes
id | string
created | timestamp
objectType | string (value is always "charge_split")
charge | string
The identifier of charge within which the split was created
amount | integer
Charge amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
The charge currency represented as a three-letter ISO currency code.
type | string
Type of split, possible value: tip
merchant | string
The merchant identifier to whom the money was transferred, always platform.
EXAMPLE OBJECT
{
"id": "spl_YUsnOoJZYap3PWwi6ByzbUYe",
"created" : 1415810800,
"objectType" : "charge_split",
"charge" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"type": "tip",
"amount" : 100,
"currency" : "USD",
"merchant": "mrc_SzA23wroCbvstqHVFYup007A"
}
Retrieve an existing Charge split
Retrieves an existing charge split object.
Attributes
CHARGE_SPLIT_ID | string, required
Identifier of the charge split object that should be retrieved.
Result
Successful request returns a charge split object.
DEFINITION
GET https://api.shift4.com/charge-splits/{CHARGE_SPLIT_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/charge-splits/spl_YUsnOoJZYap3PWwi6ByzbUYe \
-u sk_test_1Hb4bwfkN10CXQX17rdhvGzG:
EXAMPLE RESPONSE
{
"id": "spl_YUsnOoJZYap3PWwi6ByzbUYe",
"created" : 1415810800,
"objectType" : "charge_split",
"charge" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"type": "tip",
"amount" : 100,
"currency" : "USD",
"merchant": "mrc_SzA23wroCbvstqHVFYup007A"
}
List Charge Splits
List charge split objects.
Attributes
charge | string, optional
Returns only charge splits associated with a given charge
Result
A successful request returns a list of charge split objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/charge-splits
EXAMPLE REQUEST
curl "https://api.shift4.com/charge-splits?limit=3" \
-u sk_test_1Hb4bwfkN10CXQX17rdhvGzG:
EXAMPLE RESPONSE
{
"list" : [
{
"id": "spl_YUsnOoJZYap3PWwi6ByzbUYe",
"created" : 1415810800,
"objectType" : "charge_split",
"charge" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"type": "tip",
"amount" : 100,
"currency" : "USD",
"merchant": "mrc_SzA23wroCbvstqHVFYup007A"
}
{ ... },
{ ... }
],
"hasMore" : true
}
Charge Split Refunds
Charge split refund represents a refund of a charge split.
Charge split refund object
Attributes
id | string
created | timestamp
objectType | string (value is always "charge_split_refund")
amount | integer
Charge amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
The charge currency represented as a three-letter ISO currency code.
split | string
The identifier of charge split associated with given refund.
EXAMPLE OBJECT
{
"id": "sre_AXRtApKXCsr4RAso9qdfghUq",
"created" : 1415810800,
"objectType" : "charge_split_refund",
"amount" : 100,
"currency" : "USD",
"split": "spl_YUsnOoJZYap3PWwi6ByzbUYe"
}
Refund a Charge Split
Refund an existing charge split, which will result in returning funds to the merchant who created the split.
Partial refunds are not possible.
Attributes
split | string, required
Identifier of the charge split object that should be refunded.
amount | integer
Charge amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
Result
A successful request returns a charge split refund object.
DEFINITION
POST https://api.shift4.com/charge-split-refunds
EXAMPLE REQUEST
curl https://api.shift4.com/charge-split-refunds \
-u sk_test_1Hb4bwfkN10CXQX17rdhvGzG: \
-d "split=spl_YUsnOoJZYap3PWwi6ByzbUYe" \
-d "amount=100"
EXAMPLE RESPONSE
{
"id": "sre_AXRtApKXCsr4RAso9qdfghUq",
"created" : 1415810800,
"objectType" : "charge_split_refund",
"amount" : 100,
"currency" : "USD",
"split": "spl_YUsnOoJZYap3PWwi6ByzbUYe"
}
Retrieve an existing Charge split refund
Retrieves an existing charge split refund object.
Attributes
CHARGE_SPLIT_REFUND_ID | string, required
Identifier of the charge split refund object that should be retrieved.
Result
Successful request returns a charge split refund object.
DEFINITION
GET https://api.shift4.com/charge-split-refunds/{CHARGE_SPLIT_REFUND_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/charge-split-refunds/sre_AXRtApKXCsr4RAso9qdfghUq \
-u sk_test_1Hb4bwfkN10CXQX17rdhvGzG:
EXAMPLE RESPONSE
{
"id": "sre_AXRtApKXCsr4RAso9qdfghUq",
"created" : 1415810800,
"objectType" : "charge_split_refund",
"amount" : 100,
"currency" : "USD",
"split": "spl_YUsnOoJZYap3PWwi6ByzbUYe"
}
List Charge Split Refunds
List charge split refund objects.
Attributes
split | string, optional
Returns only charge split refunds associated with a given charge split.
Result
A successful request returns a list of charge split refund objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/charge-split-refunds
EXAMPLE REQUEST
curl "https://api.shift4.com/charge-split-refunds?limit=3" \
-u sk_test_1Hb4bwfkN10CXQX17rdhvGzG:
EXAMPLE RESPONSE
{
"list" : [
{
"id": "sre_AXRtApKXCsr4RAso9qdfghUq",
"created" : 1415810800,
"objectType" : "charge_split_refund",
"amount" : 100,
"currency" : "USD",
"split": "spl_YUsnOoJZYap3PWwi6ByzbUYe"
}
{ ... },
{ ... }
],
"hasMore" : true
}
Refunds
Refund represents a refund of a charge.
Refund object
Attributes
id | string
created | timestamp
amount | integer
Refund amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
Refund currency represented as a three-letter ISO currency code.
objectType | string (value is always "refund")
charge | string
ID of the charge associated with this refund.
reason | string
Reason of charge refund. Possible values are: fraudulent
status | string
Possible values are: successful, failed
metadata | metadata object, optional
EXAMPLE OBJECT
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "USD",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
}
Refund a Charge
Refund an existing charge, which will result in funds being returned to the previously charged credit or debit card.
Partial refunds are only possible for captured charge. The partial refunds can be repeated for as long as the charge is not fully refunded.
Note that if there is an active subscription related to this charge, it won't be affected by this operation. If you want to cancel a subscription, you must make it in a separate request.
Arguments
chargeId | string, required
Identifier of the charge object that should be refunded.
amount | integer, optional (default is the current amount of charge)
Amount (in minor units) to refund. This must be less or equal to the current amount of charge that is being refunded.
reason | string
Reason of charge refund. Possible values are: fraudulent
metadata | metadata object, optional
Result
A successful request returns a refund object.
DEFINITION
POST https://api.shift4.com/refunds
EXAMPLE REQUEST
curl https://api.shift4.com/refunds \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "chargeId=char_ZNmWK4pUECfFQTY0N4WMKeh3&amount=499"
EXAMPLE RESPONSE
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "USD",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
}
Retrieve an existing Refund
Arguments
REFUND_ID | string, required
Identifier of the refund object that should be retrieved.
Result
A successful request returns a refund object.
DEFINITION
GET https://api.shift4.com/refunds/{REFUND_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/refunds/re_CNiqwdKHpX3o4SD4PWJxM5CF \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "USD",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
}
Update an existing Refund
Updates an existing refund object.
Arguments
metadata | metadata object, optional
Result
A successful request returns a refund object.
DEFINITION
POST https://api.shift4.com/refunds/{REFUND_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/refunds/re_CNiqwdKHpX3o4SD4PWJxM5CF \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d '{"metadata": {"key": "value"}}'
EXAMPLE RESPONSE
{
"id": "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created": 1609325894,
"amount": 100,
"currency": "USD",
"objectType": "refund",
"charge": "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason": "fraudulent",
"status": "successful",
"metadata": {
"key": "value"
}
}
List Refunds
List refund objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
chargeId | string, required
Identifier of the charge object for which refunds should be listed.
Result
A successful request returns a list of refund objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/refunds
EXAMPLE REQUEST
curl "https://api.shift4.com/refunds?chargeId=char_ZNmWK4pUECfFQTY0N4WMKeh3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list": [
{
"id": "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created": 1609325894,
"amount": 100,
"currency": "USD",
"objectType": "refund",
"charge": "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason": "fraudulent",
"status": "successful"
},
{
"...": "..."
},
{
"...": "..."
}
],
"hasMore": true
}
Customers
Customers allows to store cards for later use and to perform automatically recurring charges. Customers are also useful for tracking charges that are associated with the same entity.
Customer object
Attributes
id | string
created | timestamp
objectType | string (value is always "customer")
email | string
description | string
defaultCardId | string
Identifier of the customer's default card.
cards | list of card object
List of 10 most recent cards associated with this customer.
metadata | metadata object
EXAMPLE OBJECT
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"description" : null,
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
],
"metadata" : { }
}
Create a Customer
Creates a new customer object.
Arguments
email | string, required
description | string, optional
card | charge identifier, card token or card details, optional
If provided, the customer will be created with this card and the card will be set as default. Can be one of the following:
card token (for example obtained from Components)
charge identifier - will save the card that was used to create a charge (only possible for successful charge not assigned to any other customer and will result in that charge being assigned to this customer)
card details (the same as in card create request)
metadata | metadata object, optional
Result
A successful request returns a customer object that represents the created customer.
DEFINITION
POST https://api.shift4.com/customers
EXAMPLE REQUEST
curl https://api.shift4.com/customers \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "[email protected]" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe"
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
}
Retrieve an existing Customer
Retrieves an existing customer object.
Arguments
CUSTOMER_ID | string, required
Identifier of the customer object that should be retrieved.
Result
A successful request returns a customer object.
DEFINITION
GET https://api.shift4.com/customers/{CUSTOMER_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
}
Update an existing Customer
Update an existing customer object.
Any not provided parameter will be left unchanged.
Arguments
CUSTOMER_ID | string, required
Identifier of the customer object that should be updated.
email | string, optional
description | string, optional
defaultCardId | string, optional
Identifier of the customer's card that will be set as the default one.
card | charge identifier, card token or card details, optional
If provided, the new card will be added to the customer's cards and the card will be set as default. Can be one of the following:
card token (for example obtained from Components)
charge identifier - will save the card that was used to create a charge (only possible for successful charge not assigned to any other customer, and will result in that charge being assigned to this customer)
card details (same as in card create request)
metadata | metadata object ,optional
Result
A successful request returns a customer object that was updated.
DEFINITION
POST https://api.shift4.com/customers/{CUSTOMER_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "[email protected]" \
-d "description=New description"
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"description" : "New description",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
}
Delete a Customer
Deletes an existing customer object.
Arguments
CUSTOMER_ID | string, required
Identifier of the customer object that should be deleted.
Result
A successful request returns identifier of the deleted customer object.
DEFINITION
DELETE https://api.shift4.com/customers/{CUSTOMER_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
}
List Customers
List customer objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
deleted | boolean, optional (default is false)
Can be used to list deleted objects.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
email | string, optional
Returns only customers with a given email.
Result
A successful request returns a list of customer objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/customers
EXAMPLE REQUEST
curl "https://api.shift4.com/customers?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
},
{ ... },
{ ... }
],
"hasMore" : false
}
Cards
Card represents a credit or a debit card.
Cards are used to save credit or debit card data for later use. Cards can also be used to represent card data in other operations (for example to specify card data when creating a new charge).
Card object
Attributes
id | string
created | timestamp
objectType | string (value is always "card")
first6 | integer
last4 | integer
fingerprint | string
Unique identifier of the card number. Can be used to check if two different charges were done using the same card number.
expMonth | integer
expYear | integer
cardholderName | string
customerId | string
Identifier of the customer that is the owner of this card.
brand | string
Brand of card. Possible values are: Visa
, American Express
, MasterCard
, Discover
, JCB
, Diners Club
, Unknown
type | string
Type of card. Possible values are: Credit Card
, Debit Card
, Prepaid Card
, Unknown
country | string
Country of card's Issuing Bank (represented as a two-letter ISO country code). This value is derived from the card's Bank Identification Number (BIN).
issuer | string
Name of card's Issuing Bank
addressLine1 | string
addressLine2 | string
addressCity | string
addressState | string
addressZip | string
addressCountry | string
Country represented as a three-letter ISO country code.
fraudCheckData | object
Additional data used for fraud protection. Can contain the following attributes:
ipAddress (string) - IP address of the user
ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)
email (string) - e-mail address of the user
phone (string) - phone number of the user
userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token
merchantAccountId | string
Identifier of the merchant account that was used to create this card.
fastCredit | object
Additional data present if this card was checked for support of fast credits. This check can be performed by updating card with checkFastCredit = true
. Contains the following attributes:
supported (boolean) - Indicates whether the card supports fast credit
updated (timestamp) - Indicated the last time fast credit status has been refreshed
EXAMPLE OBJECT
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH",
"fastCredit" : {
"supported" : true,
"updated" : 1415811511
}
}
Create a new Card
Creates a new card object.
There are three ways to create a new card object:
use card token (for example obtained from Components)
use charge identifier - will save the card that was used to create a charge (only possible for successful charge not assigned to any other customer and will result in that charge being assigned to this customer)
specify all card details (as seen in the arguments list below)
Arguments
number | string, required
Card number without any separators.
expMonth | string, required
Card expiration month.
expYear | string, required
Card expiration year.
cvc | string, required
Card security code.
cardholderName | string, optional
addressLine1 | string, optional
addressLine2 | string, optional
addressCity | string, optional
addressState | string, optional
addressZip | string, optional
addressCountry | string, optional
Country represented as a three-letter ISO country code.
fraudCheckData | object
Additional data used for fraud protection. Can contain the following attributes:
ipAddress (string) - IP address of the user
ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)
email (string) - e-mail address of the user
phone (string) - phone number of the user, eg. +12345678901
userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token
Result
A successful request returns a card object that represents the created card.
DEFINITION
POST https://api.shift4.com/customers/{CUSTOMER_ID}/cards
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "id=tok_NGsyDoJQXop5Pqqi6HizbJTe"
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
Retrieve an existing Card
Retrieves an existing card object.
Arguments
CUSTOMER_ID | string, required
Identifier of the customer object that is the owner of the card object that should be retrieved.
CARD_ID | string, required
Identifier of the card object that should be retrieved.
Result
A successful request returns a card object.
DEFINITION
GET https://api.shift4.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
Update an existing Card
Arguments
CUSTOMER_ID | string, required
Identifier of the customer object that is the owner of the card object that should be updated.
CARD_ID | string, required
Identifier of the card object that should be updated.
expMonth | integer
expYear | integer
cardholderName | string, optional
addressCity | string
addressState | string
addressZip | string
addressCountry | string
Country represented as a three-letter ISO country code.
addressLine1 | string
addressLine2 | string
checkFastCredit | boolean, optional
Indicates whether a check for fast credit support should be made.
Result
A successful request returns a card object that was updated.
DEFINITION
POST https://api.shift4.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "cardholderName=Jane Doe"
-d "checkFastCredit=true"
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2027",
"cardholderName" : "Jane Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH",
"fastCredit" : {
"supported" : true,
"updated" : 1415811511
}
}
Delete a Card
Deletes an existing card object.
If you delete the card that is the current default card, then the most recently added card will be used as the new default card. If you delete the last card then teh default card will be set to null
.
Arguments
CUSTOMER_ID | string, required
Identifier of the customer object that is the owner of the card object that should be deleted.
CARD_ID | string, required
Identifier of the card object that should be deleted.
Result
A successful request returns the identifier of the deleted card object.
DEFINITION
DELETE https://api.shift4.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id": "card_8P7OWXA5xiTS1ISnyZcum1KV",
}
List Cards
List card objects for a given customer.
Arguments
customerId | string, required
Identifier of the customer object whose cards should be listed.
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
deleted | boolean, optional (default is false)
Can be used to list deleted objects.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
Result
A successful request returns a list of card objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/customers/{CUSTOMER_ID}/cards
EXAMPLE REQUEST
curl "https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
{ ... },
{ ... }
],
"hasMore" : false
}
Subscriptions
A subscription represents a recurring payment that will result in a charge being automatically created for a given customer. The frequency and amount of these automatic charges are defined by a plan.
Subscriptions are always billed to the customer's current default card.
Subscription object
Attributes
id | string
created | timestamp
objectType | string (value is always "subscription")
planId | string
Identifier of a plan assigned to this subscription.
customerId | string
Identifier of a customer who is the owner of this subscription.
quantity | integer
Multiplier that will be applied to change the amount defined in a plan. For example a plan with amount=100
used in the subscription with quantity=5
will result in changes with amount=500
.
captureCharges | boolean
Whatever charges created by this subscription will be immediately captured (see captured attribute in charge request). If set to false
, then you need to manually capture each charge created by this subscription.
status | string
Status of this subscription. Possible values are:
trialing
- subscription was created from a plan with trial days and is still in the trial periodactive
- subscription is active and will be renewed after the end of a current billing cyclepast_due
- renewing of subscription has failedcanceled
- subscription was manually canceled, or all retry renewal attempts have failedunpaid
- all retry renewal attempts have failedincomplete
- the first charge has failed on subscription creation
Note that the resulting status when all renewal retry attempts have failed depend on your account settings.
remainingBillingCycles | integer
Defines how many billing cycles remain before this subscription is automatically canceled.
start | timestamp
Date the subscription started using the current plan.
The value will have different than created
, if the subscription plan was changed.
currentPeriodStart | timestamp
Start of the current billing period.
For an active subscription this should match the time of last rebill, but can be different if there was a problem creating the rebill charge (for example, because of the declined charge).
currentPeriodEnd | timestamp
End of the current billing period.
For an active subscription this is the time when the next rebill will be attempted.
canceledAt | timestamp
The date when the subscription was requested to be canceled.
endedAt | timestamp
The date when the subscription was canceled.
Will have a different value than canceledAt
, if the subscription was canceled with atPeriodEnd=true
.
trialStart | timestamp
Start of the trial period.
trialEnd | timestamp
End of the trial period.
cancelAtPeriodEnd | boolean
If set to true
, then the subscription will be canceled at the end of the current billing period.
shipping | object
Shipping details. Can contain the following attributes:
name (string) - name of the recipient
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
phone (string) - phone of the recipient
billing | object
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
email (string) - email of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a wo-letter ISO country code
phone (string) - phone of billed person or company
vat (string) - tax identification number
merchantAccountId | string
Identifier of the merchant account that will be used to create charges for this subscription.
metadata | metadata object
EXAMPLE OBJECT
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"remainingBillingCycles" : null,
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"canceledAt" : null,
"endedAt" : null,
"trialStart" : null,
"trialEnd" : null,
"cancelAtPeriodEnd" : false,
"metadata" : {}
}
Create a new Subscription
Creates a new subscription object.
Arguments
customerId | string, required
Identifier of a customer who will be the owner of this subscription.
planId | string, required
Identifier of a plan that will be assigned to this subscription.
card | charge identifier, card token or card details, optional
If provided, the new card will be added to the customer's cards and it will be set as default. Can be one of the following:
card token (for example, obtained from Components)
charge identifier - will save the card that was used to create a charge (only possible for a successful charge not assigned to any other customer and will result in that charge being assigned to this customer)
card details (the same as in card create request)
quantity | integer, optional (default is 1)
captureCharges | boolean, optional (default is true)
Any charges created by this subscription will be captured immediately (see captured attribute in charge request). If set to false
, then you need to manually capture each charge created by this subscription.
trialEnd | timestamp, optional
Defines the end of the trial period for this subscription. If provided, then it will override the trial setting defined in the plan.
shipping | object, optional
Shipping details. Can contain the following attributes:
name (string) - name of the recipient
address (object) - address object, can contain following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as two-letter ISO country code
phone (string) - phone of the recipient, eg. +12345678901
billing | object, optional
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
phone (string) - phone of billed person or company, eg. +12345678901
vat (string) - tax identification number
merchantAccountId | string, optional
Identifier of the merchant account that will be used to create charges for this subscription.
metadata | metadata object
Result
A successful request returns a subscription object that represents created subscription.
DEFINITION
POST https://api.shift4.com/subscriptions
EXAMPLE REQUEST
curl https://api.shift4.com/subscriptions \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "planId=plan_bLu3vzO8yhAFhbxFEadm6HUV" \
-d "customerId=cust_AoR0wvgntQWRUYMdZNLYMz5R"
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
}
Retrieve an existing Subscription
Retrieves an existing subscription object.
Arguments
SUBSCRIPTION_ID | string, required
Identifier of the subscription object that should be retrieved.
Result
A successful request returns a subscription object.
DEFINITION
GET https://api.shift4.com/subscriptions/{SUBSCRIPTION_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
}
Update an existing Subscription
Update an existing subscription object.
Any not provided parameter will be left unchanged.
Arguments
SUBSCRIPTION_ID | string, required
Identifier of the subscription object that should be updated.
planId | string, optional
Identifier of a plan that will be assigned to this subscription.
card | charge identifier, card token or card details, optional
If provided, the new card will be added to the customer's cards and it will be set as default. Can be one of the following:
card token (for example, obtained from Components)
charge identifier - will save the card that was used to create a charge (only possible for successful charge that is not assigned to any other customer and will result in that charge being assigned to this customer)
card details (the same as in the card create request)
quantity | integer, optional
captureCharges | boolean, optional
Any charges created by this subscription will be captured immediately (see captured attribute in the charge request). If set to false
then you need to manually capture each charge created by this subscription.
currentPeriodEnd | string, optional
Defines the end of the current cycle for this subscription and a billing date for the next one. Should be sent as a timestamp. Special value of now
can be used to end the cycle and start a new one immediately. If subscription is currently in trialing
status, it affects the trial period.
shipping | object, optional
Shipping details. Can contain the following attributes:
name (string) - name of the recipient
address (object) - address object, can contain following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as two-letter ISO country code
phone (string) - phone of the recipient, eg. +12345678901
billing | object, optional
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
phone (string) - phone of billed person or company, eg. +12345678901
vat (string) - tax identification number
merchantAccountId | string, optional
Identifier of the merchant account that will be used to create charges for this subscription.
metadata | metadata object, optional
Result
A successful request returns a subscription object that was updated.
DEFINITION
POST https://api.shift4.com/subscriptions/{SUBSCRIPTION_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "quantity=5"
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 5,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
}
Cancel a Subscription
Cancels an existing subscription.
Arguments
SUBSCRIPTION_ID | string, required
Identifier of the subscription object that should be canceled.
atPeriodEnd | boolean, optional (default is false)
Whether or not to delay cancellation of the subscription until the end of the current period. By default the subscription is canceled immediately.
Result
A successful request returns a subscription object that was canceled.
DEFINITION
DELETE https://api.shift4.com/subscriptions/{SUBSCRIPTION_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE REQUEST (with atPeriodEnd)
curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5?atPeriodEnd=true \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "canceled",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"canceledAt" : 1415982979,
"endedAt" : 1415982979,
"cancelAtPeriodEnd" : false
}
List Subscriptions
Lists subscription objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
deleted | boolean, optional (default is false)
Can be used to list deleted objects.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
customerId | string, optional
Identifier of the customer object whose subscriptions should be listed.
planId | string, optional
Identifier of the plan object whose subscriptions should be listed.
Result
A successful request returns a list of subscription objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/subscriptions
EXAMPLE REQUEST
curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
},
{ ... },
{ ... }
],
"hasMore" : true
}
Plans
Plan represents an automatically recurring charge.
Plans are used when a subscription is created for a customer to define how often and how much a given customer will be charged.
Plan object
Attributes
id | string
created | timestamp
objectType | string (value is always "plan")
amount | integer
Subscription charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
Subscription charge currency represented as three-letter ISO currency code.
interval | string
Frequency of subscription charges. Possible values are: hour
, day
, week
, month
, year
intervalCount | integer
Number of intervals between subscription charges. For example interval=day
and intervalCount=10
will result in charge every 10 days.
billingCycles | integer
Number of charges after which subscription will be automatically canceled. Value of null
means no limit on number of charges.
name | string
Display name of this plan
trialPeriodDays | integer
Number of days between creation of subscription and the first charge.
recursTo | plan identifier
When subscription is automatically canceled (due to reaching limit of billingCycles
) it will move to plan defined by this attribute.
metadata | metadata object
EXAMPLE OBJECT
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "USD",
"interval" : "day",
"intervalCount" : 10,
"billingCycles" : null,
"name" : "Example plan",
"trialPeriodDays" : null,
"recursTo" : null,
"metadata" : {}
}
Create a Plan
Creates a new plan object.
Arguments
amount | integer, required
Subscription charge amount in minor units of a given currency. For example, 10€ is represented as "1000", and 10¥ is represented as "10".
currency | string, required
Subscription charge currency represented as a three-letter ISO currency code.
interval | string, required
Frequency of the subscription charges. Possible values are: hour
, day
, week
, month
, year
name | string, required
Displays the name of this plan
intervalCount | integer, optional (default is 1)
Number of intervals between the subscription charges. For example, interval=day
and intervalCount=10
will result in a charge every 10 days.
billingCycles | integer, optional
Number of charges after which the subscription will be automatically canceled. Value of null
means no limit on the number of charges.
trialPeriodDays | integer, optional (default is 0)
Number of days between the creation of the subscription and the first charge.
recursTo | plan identifier, optional
When the subscription is automatically canceled (due to reaching limit of billingCycles
) it will move to the plan defined by this attribute.
metadata | metadata object, optional
Result
A successful request returns a plan object that represents the created plan.
DEFINITION
POST https://api.shift4.com/plans
EXAMPLE REQUEST
curl https://api.shift4.com/plans \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=USD" \
-d "interval=day" \
-d "intervalCount=10" \
-d "name=Example plan"
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "USD",
"interval" : "day",
"intervalCount" : 10,
"name" : "Example plan",
"trialPeriodDays" : 0
}
Retrieve an existing Plan
Retrieves an existing plan object.
Arguments
PLAN_ID | string, required
Identifier of the plan object that should be retrieved.
Result
A successful request returns a plan object.
DEFINITION
GET https://api.shift4.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "USD",
"interval" : "day",
"intervalCount" : 10,
"name" : "Example plan",
"trialPeriodDays" : 0
}
Update an existing Plan
Update an existing plan object.
Any not provided parameter will be left unchanged.
Changing amount
or currency
of a plan will only affect future rebills of all subscriptions that are using this plan.
Arguments
PLAN_ID | string, required
Identifier of the plan object that should be updated.
amount | integer, optional
Subscription charge amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string, optional
Subscription charge currency represented as a three-letter ISO currency code.
name | string, optional
Displays the name of this plan
metadata | metadata object, optional
Result
A successful request returns a plan object that was updated.
DEFINITION
POST https://api.shift4.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "name=New plan"
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "USD",
"interval" : "day",
"intervalCount" : 10,
"name" : "New plan",
"trialPeriodDays" : 0
}
Delete a Plan
Deletes an existing plan object.
Note that when you delete a plan, the existing subscriptions will continue to be charged until they are canceled.
Arguments
PLAN_ID | string, required
Identifier of the plan object that should be deleted.
Result
A successful request returns identifier of the deleted plan object.
DEFINITION
DELETE https://api.shift4.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id": "plan_bLu3vzO8yhAFhbxFEadm6HUV",
}
List Plans
List plan objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
deleted | boolean, optional (default is false)
Can be used to list deleted objects.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
Result
A successful request returns a list of plan objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
DELETE https://api.shift4.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "USD",
"interval" : "day",
"intervalCount" : 10,
"name" : "Example plan",
"trialPeriodDays" : 0
},
{ ... },
{ ... }
],
"hasMore" : true
Events
Events can be used to get notifications when something interesting has happened. For example, the creation of a new successful charge will result in CHARGE_SUCCEEDED
event.
We provide API methods to retrieve a single event and to list events. It is also possible to get notifications about the new events by using Webhooks.
Event object
Attributes
id | string
created | timestamp
objectType | string (value is always "event")
type | string
Type of event. For more information see list of event types.
data | object
Object that is a subject of this event. For example, an event with type=CHARGE_SUCCEEDED
will have a charge object as the value of this attribute.
log | string
Identifier of request log associated with this event.
EXAMPLE OBJECT
{
"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
"created" : 1416305114,
"objectType" : "event",
"type" : "CHARGE_SUCCEEDED",
"data" : {
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}
Retrieve an Event
Retrieves an existing event object.
Arguments
EVENT_ID | string, required
Identifier of the event object that should be retrieved.
Result
A successful request returns an event object.
DEFINITION
GET https://api.shift4.com/events/{EVENT_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/events/event_EY7CzyQiffJykW8rC5wSRnAj \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
"created" : 1416305114,
"objectType" : "event",
"type" : "CHARGE_SUCCEEDED",
"data" : {
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}
List Events
List event objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
Result
A successful request returns a list of event objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/events
EXAMPLE REQUEST
curl "https://api.shift4.com/events?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
"created" : 1416305114,
"objectType" : "event",
"type" : "CHARGE_SUCCEEDED",
"data" : {
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "USD",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
},
{ ... },
{ ... }
],
"hasMore" : true
}
Types of Events
CHARGE_SUCCEEDED
| a charge object
Occurs when a new charge is successfully created.
CHARGE_PENDING
| a charge object
Occurs when a new charge processing is pending.
CHARGE_FAILED
| a charge object
Occurs when the creation of a new charge fails.
CHARGE_UPDATED
| a charge object
Occurs when a charge object is updated.
CHARGE_CAPTURED
| a charge object
Occurs when a charge is captured.
CHARGE_REFUNDED
| a charge object
Occurs when a charge is refunded.
CHARGE_DISPUTE_CREATED
| a charge object
Occurs when a customer disputes a charge (either the chargeback or the retrieval request).
CHARGE_DISPUTE_UPDATED
| a charge object
Occurs when an existing dispute is updated.
CHARGE_DISPUTE_WON
| a charge object
Occurs when a dispute is resolved as won.
CHARGE_DISPUTE_LOST
| a charge object
Occurs when a dispute is resolved as lost.
CHARGE_DISPUTE_FUNDS_WITHDRAWN
| a charge object
Occurs when funds are removed from your account as a result of a dispute (a chargeback).
CHARGE_DISPUTE_FUNDS_RESTORED
| a charge object
Occurs when previously withdrawn funds are restored as a result of a winning dispute.
CUSTOMER_CREATED
| a customer object
Occurs when new a customer is created.
CUSTOMER_UPDATED
| a customer object
Occurs when a customer is updated.
CUSTOMER_DELETED
| a customer object
Occurs when a customer is deleted.
CUSTOMER_CARD_CREATED
| a card object
Occurs when a new card is created for a customer.
CUSTOMER_CARD_UPDATED
| a card object
Occurs when a customer's card is updated.
CUSTOMER_CARD_DELETED
| a card object
Occurs when a customer's card is deleted.
CUSTOMER_SUBSCRIPTION_CREATED
| a subscription object
Occurs when a new subscription is created for a customer.
CUSTOMER_SUBSCRIPTION_UPDATED
| a subscription object
Occurs when a customer's subscription is updated.
CUSTOMER_SUBSCRIPTION_DELETED
| a subscription object
Occurs when a customer's subscription is cancelled.
PLAN_CREATED
| a plan object
Occurs when a new plan is created.
PLAN_UPDATED
| a plan object
Occurs when a plan is updated.
PLAN_DELETED
| a plan object
Occurs when a plan is deleted.
CREDIT_SUCCEEDED
| a credit object
Occurs when a new credit is successfully created.
CREDIT_FAILED
| a credit object
Occurs when the creation of a new credit fails.
CREDIT_UPDATED
| a credit object
Occurs when a credit object is updated.
FRAUD_WARNING_CREATED
| a fraud warning object
Occurs when a fraud warning is created.
FRAUD_WARNING_UPDATED
| a fraud warning object
Occurs when a fraud warning is updated.
PAYOUT_CREATED
| a payout object
Occurs when a payout is created.
PAYOUT_UPDATED
| a payout object
Occurs when a payout is updated.
PAYOUT_CREATED
| a payout object
Occurs when a payout is created.
PAYMENT_METHOD_CREATED
| a payment method object
Occurs when a new payment method is successfully created.
PAYMENT_METHOD_UPDATED
| a payment method object
Occurs when a payment method object is updated.
PAYMENT_METHOD_DELETED
| a payment method object
Occurs when a payment method object is deleted.
PAYMENT_LINK_CREATED
| a payment link object
Occurs when a payment link object is created.
PAYMENT_LINK_UPDATED
| a payment links object
Occurs when a payment method object is updated, deactivated or reactivated.
CHARGE_SPLIT_CREATED
| a charge split object
Occurs when a charge split is created..
CHARGE_SPLIT_REFUND_CREATED
| a charge split refund object
Occurs when a charge split refund is created..
Tokens
Tokens are used to represent a card in a situation where you don't want to process or store card-sensitive data on your servers. Tokens can be easily created directly in a browser with the use of Components, but you can also create tokens in other environments (for example, in mobile applications).
Tokens can be created with the use of either "API Public Key" or "API Secret Key". You can safely embed your "API Public Key" in JavaScript or in downloadable applications (like iPhone or Android apps), so you can easily create tokens directly from these applications.
Note that tokens are meant to be used as a temporary representation of card data, and each token can be used only once. You should not store tokens for long periods of time - if you want to store a card for later use you should use the token to either create new customer or add new card to the existing customer.
Token object
Attributes
id | string
created | timestamp
objectType | string (value is always "token")
first6 | integer
last4 | integer
fingerprint | integer
Unique identifier of the card number. Can be used to check if two different charges were done using the same card number.
expMonth | integer
expYear | integer
brand | string
Brand of card. Possible values are: Visa
, American Express
, MasterCard
, Discover
, JCB
, Diners Club
, Unknown
type | string
Type of card. Possible values are: Credit Card
, Debit Card
, Prepaid Card
, Unknown
cardholderName | string
addressLine1 | string
addressLine2 | string
addressCity | string
addressState | string
addressZip | string
addressCountry | string
Country represented as a three-letter ISO country code.
used | boolean
card | card object
Card that was created from this token.
fraudCheckData | object
Additional data used for fraud protection. Can contain the following attributes:
ipAddress (string) - IP address of the user
ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)
email (string) - e-mail address of the user
phone (string) - phone number of the user
userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token
threeDSecureInfo | object
Additional data present if card (represented by this token) was verified with 3D Secure. Can contain following attributes:
amount (integer) - amount in minor units that was used in 3D Secure
currency (string) - currency that was used in 3D Secure (represented as a three-letter ISO currency code)
enrolled (boolean) - information on whether the card used to create this charge supports 3D Secure
liabilityShift (string) - can have one of the following values:
null
- 3D Secure was not started or is in progresssuccessful
- 3D Secure was completed successfullyfailed
- 3D Secure is supported, but was not completed successfullynot_possible
- 3D Secure is not supportedauthenticationFlow (string) - can have one of the following values:
frictionless
- Issuer authenticated the customer via the frictionless flow.challenge
- Issuer authenticated the customer by showing a challenge window.
EXAMPLE OBJECT
{
"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
"created" : 1415810511,
"objectType" : "token",
"first6" : "42424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"brand" : "Visa",
"type" : "Credit Card",
"country" : "CH",
"used" : true,
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
Create a new Token
Creates a new token object.
This method can be called with either "API Public Key" or "API Secret Key".
Attributes
number | string, required
Card number without any separators.
expMonth | string, required
Card expiration month.
expYear | string, required
Card expiration year.
cvc | string, required
Card security code.
cardholderName | string, optional
addressLine1 | string, optional
addressLine2 | string, optional
addressCity | string, optional
addressState | string, optional
addressZip | string, optional
addressCountry | string, optional
Country represented as a three-letter ISO country code.
fraudCheckData | object
Additional data used for fraud protection. Can contain the following attributes:
ipAddress (string) - IP address of the user
ipCountry (string) - country derived from user's IP address (represented as two-letter ISO country code)
email (string) - e-mail address of the user
phone (string) - phone number of the user, eg. +12345678901
userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
This attribute is only supported for requests made with "API Secret Key".
For requests made with "API Public Key" value of this attribute is ignored and data is automatically collected from request.
Result
Successful request returns a token object that represents given card details.
DEFINITION
POST https://api.shift4.com/tokens
EXAMPLE REQUEST
curl https://api.shift4.com/tokens \
-u pu_test_WVMFC9GFuvm54b0uorifKkCh: \
-d "number=4242424242424242" \
-d "expMonth=11" \
-d "expYear=2028" \
-d "cvc=123" \
-d "cardholderName=John Doe"
EXAMPLE RESPONSE
{
"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
"created" : 1415810511,
"objectType" : "token",
"first6" : "42424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2027",
"cardholderName" : "John Doe",
"brand" : "Visa",
"type" : "Credit Card",
"country" : "CH",
"used" : false
}
Retrieve an existing Token
Retrieves an existing token object.
Arguments
TOKEN_ID | string, required
Identifier of the token object that should be retrieved.
Result
A successful request returns a token object.
DEFINITION
GET https://api.shift4.com/tokens/{TOKEN_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/tokens/tok_NGsyDoJQXop5Pqqi6HizbJTe \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
"created" : 1415810511,
"objectType" : "token",
"first6" : "42424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2027",
"cardholderName" : "John Doe",
"brand" : "Visa",
"type" : "Credit Card",
"country" : "CH",
"used" : false
}
Initialize 3D Secure Process
Initialize a new 3D Secure authentication process.
Generally (apart from a few specialized use cases) it is not recommended to initialize 3D Secure from the API. You should use our Components or checkout integration that already supports 3D Secure authentication.
To complete the 3D Secure process initiated using this API call, you must:
Ensure that the card supports 3D Secure by checking that
enrolled
filed in response is equal totrue
Redirect the user to
redirectUrl
or display that URL in an <iframe> tag.Wait for the user to return to
returnUrl
Use
token
to create a charge
Arguments
amount | integer, required
Amount used in the 3D Secure process (in minor units of a given currency). Must match amount that will be used later to create a charge. For exampl, 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string, required
Currency used in the 3D Secure process (represented as a three-letter ISO currency code). Must match currency that will be used later to create a charge.
returnUrl | string, required
URL that will be displayed to the user after the 3D Secure process is completed. Following parameters are appended to this URL:
token (string) - identifier of a token that was used for this 3D Secure process
liabilityShift (string) - can be one of the following:
successful
orfailed
card | card token, card details or card identifier, required
Can be one of the following:
card token (for example, obtained from Components)
card details (the same as in card create request)
card identifier (must be an existing card that is associated with a customer)
If neither card nor payment method is provided, the customer's defaults will be used.
Result
A successful request returns an object with the following attributes:
enrolled | boolean
Whether the card used to start this 3D Secure process supports 3D Secure.
version | string
Version of 3D Secure which will be used for this 3D Secure process.
redirectUrl | string
URL that must be used to complete the 3D Secure process by the user. User must be either redirected to this URL or this URL must be displayed to the user in an <iframe> tag.
token | token object
Token that is being used for this 3D Secure process. This token must be used to create charge after this 3D Secure process is completed.
DEFINITION
POST https://api.shift4.com/3d-secure
EXAMPLE REQUEST
curl https://api.shift4.com/3d-secure \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=USD" \
-d "card[number]=4012001800000016" \
-d "card[expMonth]=11" \
-d "card[expYear]=2028" \
-d "card[cvc]=123" \
-d "returnUrl=https://example.com/"
EXAMPLE RESPONSE
{
"enrolled": true,
"version": "2.2.0",
"redirectUrl": "https://api.shift4.com/3d-secure/start/35WSIRL2Qm1JKsDXMohFVhGVj5AFptAhuN7Sa0oQ",
"token": {
"id": "tok_RBZVaNlPj70nNIQ2cIB2lYMI",
"created": 1634561057,
"objectType": "token",
"first6": "401200",
"last4": "0016",
"fingerprint": "8bTF2cbb2ccGr7ws",
"expMonth": "11",
"expYear": "2028",
"brand": "Visa",
"type": "Credit Card",
"country": "CH",
"used": false,
"threeDSecureInfo": {
"amount": 499,
"currency": "USD",
"enrolled": true,
"liabilityShift": "failed",
"version": "2.2.0",
"authenticationFlow": null
}
}
}
Blacklist
Blacklist can be used to block unwanted charges.
Blacklist contains Blacklist Rule objects. Each such object represents a single condition - if request to create a new charge matches this condition then it will fail - resulting in error response with code=blacklisted
.
Blacklist Rule object
Attributes
id | string
created | timestamp
objectType | string (value is always "blacklistRule")
ruleType | string, required
fingerprint - will blacklist based on the card's fingerprint (see fingerprint in card object)
ip_address - will blacklist based on the user's IP address (see fraudCheckData.ipAddress in card object)
ip_country - will blacklist based on the country derived from user's IP address (see fraudCheckData.ipCountry in card object)
metadata - will blacklist based on metadata entry from charge (see metadata in charge object)
email - will blacklist based on the user's email (see email in customer object and fraudCheckData.email in card object)
user_agent - will blacklist based on the "User-Agent" HTTP header (see fraudCheckData.userAgent in card object)
accept_language - will blacklist based on the "Accept-Language" HTTP header (see fraudCheckData.acceptLanguage in card object)
card_country - will blacklist based on the country of the card's issuing bank (see country in card object)
card_bin - will blacklist based on the card's BIN (see first6 in card object)
card_issuer - will blacklist based on the name of the card's issuing bank (see issuer in card object)
fingerprint | string
Used for ruleType=fingerprint
.
ipAddress | string
Used for ruleType=ip_address
.
ipCountry | string
Used for ruleType=ip_country
.
metadataKey | string
Used for ruleType=metadata
.
metadataValue | string
Used for ruleType=metadata
.
email | string
Used for ruleType=email
.
userAgent | string
Used for ruleType=user_agent
.
acceptLanguage | string
Used for ruleType=accept_language
.
cardCountry | string
Used for ruleType=card_country
.
cardBin | string
Used for ruleType=card_bin
.
cardIssuer | string
Used for ruleType=card_issuer
.
EXAMPLE OBJECT
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
}
Create a Blacklist Rule
Creates a new blacklist rule object.
Arguments
ruleType | string, required
Type of a blacklist rule. Can have one of the following values:
fingerprint - will blacklist based on the card's fingerprint (see fingerprint in card object)
ip_address - will blacklist based on the user's IP address (see fraudCheckData.ipAddress in card object)
ip_country - will blacklist based on the country derived from the user's IP address (see fraudCheckData.ipCountry in card object)
metadata - will blacklist based on metadata entry from charge (see metadata in charge object)
email - will blacklist based on the user's email (see email in customer object and fraudCheckData.email in card object)
user_agent - will blacklist based on the "User-Agent" HTTP header (see fraudCheckData.userAgent in card object)
accept_language - will blacklist based on the "Accept-Language" HTTP header (see fraudCheckData.acceptLanguage in card object)
card_country - will blacklist based on the country of the card's issuing bank (see country in card object)
card_bin - will blacklist based on the card's BIN (see first6 in card object)
card_issuer - will blacklist based on the name of the card's issuing bank (see issuer in card object)
fingerprint | string
Used for ruleType=fingerprint
.
cardNumber | string
Used for ruleType=fingerprint
. If a card number is provided, it will be automatically converted to a fingerprint. When creating fingerprint
rule then you must provide either a fingerprint or a card number, but not both.
ipAddress | string
Used for ruleType=ip_address
.
ipCountry | string
Used for ruleType=ip_country
.
metadataKey | string
Used for ruleType=metadata
.
metadataValue | string
Used for ruleType=metadata
.
email | string
Used for ruleType=email
.
userAgent | string
Used for ruleType=user_agent
.
acceptLanguage | string
Used for ruleType=accept_language
.
cardCountry | string
Used for ruleType=card_country
.
cardBin | string
Used for ruleType=card_bin
.
cardIssuer | string
Used for ruleType=card_issuer
.
Result
A successful request returns a blacklist rule object that represents created blacklist rule.
DEFINITION
POST https://api.shift4.com/blacklist
EXAMPLE REQUEST
curl https://api.shift4.com/blacklist \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "ruleType=fingerprint" \
-d "fingerprint=e3d8suyIDgFg3pE7"
EXAMPLE RESPONSE
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
}
Retrieve an existing Blacklist Rule
Retrieves an existing blacklist rule object.
Arguments
BLACKLIST_RULE_ID | string, required
Identifier of a blacklist rule object that should be retrieved.
Result
A successful request returns a blacklist Rule object.
DEFINITION
GET https://api.shift4.com/blacklist/{BLACKLIST_RULE_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/blacklist/blr_O3y7VyxbszuezuDNjuBsExUf \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
}
Delete a Blacklist Rule
Deletes an existing blacklist rule object.
Arguments
BLACKLIST_RULE_ID | string, required
Identifier of a blacklist rule object that should be deleted.
Result
A successful request returns identifier of a deleted blacklist rule object.
DEFINITION
DELETE https://api.shift4.com/blacklist/{BLACKLIST_RULE_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/blacklist/blr_O3y7VyxbszuezuDNjuBsExUf \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf"
}
Checkout Request
Checkout Request is used to define an action that will be executed after the customer has provided his card data in Checkout.
Checkout Request can define either a single charge or an automatically recurring subscription. If you already have customer object that represents your customer, you can include its identifier in Checkout Request so that the created charge or subscription will be automatically assigned to that customer. If the identifier of an existing customer is not provided in Checkout Request then a new customer object will be automatically created.
Creating Checkout Request can be done offline (without the need to communicate with Shift4 servers). All you need to do is to sign the Checkout Request object with your secret key - see signing a Checkout Request.
Checkout Request object
Arguments
charge | object, optional (either charge, subscription or customCharge is required)
Defines charge that will be created by Checkout. Can contain the following attributes:
amount (integer, required) - Charge amount in minor units of a given currency
currency (string, required) - Charge currency represented as a three-letter ISO currency code
capture (boolean, optional, default is true) - Information whether this charge should be immediately captured
metadata (metadata object, optional)
For more information about the meaning of these attributes, see charge create request.
subscription | object, optional (either charge, subscription or customCharge is required)
Defines the subscription that will be created by Checkout. Can contain the following attributes:
planId (string, required) - Identifier of a plan that will be assigned to this subscription
captureCharges (boolean, optional, default is true) - Whatever charges created by this subscription will be immediately captured
metadata (metadata object, optional)
For more information about the meaning of these attributes see subscription create request.
customCharge | object, optional (either charge, subscription or customCharge is required)
Defines the charge with the custom amount that will be selected by the customer in Checkout. Can contain the following attributes:
amountOptions (list of integers, either amountOptions or customAmount is required) - List of predefined amounts (in minor units of a given currency) that the customer can choose from.
customAmount (object, either amountOptions or customAmount is required) - Object with
min
andmax
attributes that defines a valid range for the custom amount that is provided by the customer.currency (string, required) - Charge currency represented as a three-letter ISO currency code
capture (boolean, optional, default is true) - Information whether this charge should be immediately captured
metadata (metadata object, optional)
Providing amountOptions
attribute will cause Checkout to have buttons with predefined amounts from which the customer will be able to choose. Providing customAmount
attribute will cause Checkout to have the input field where the customer can type any amount (but that amount must be within specified min/max range). Providing both of these attributes at the same time will cause Checkout to have both options - buttons with predefined amounts and the input field to provide any custom amount.
customerId | string, optional
Identifier of the existing customer that will be used to create a charge or a subscription.
termsAndConditionsUrl | string, optional
URL to your terms and conditions page. If provided, the additional page will be shown in Checkout before the payment page. On that page the customer will have to accept your terms and conditions. Additionally, if Checkout Request creates a subscription, then information about a recurring payment is also shown on that page.
threeDSecure | object, optional
3D Secure options. Can contain the following attributes:
enable (boolean, default is false) - whether 3D secure verification should be attempted
requireEnrolledCard (boolean, default is false) - the charge will fail if the card doesn't support 3D Secure (is not enrolled for 3D Secure verification)
requireSuccessfulLiabilityShiftForEnrolledCard (boolean, default is true) - the charge will fail when the card supports 3D Secure verification, but that verification was not successful (i.e. customer cancelled the verification or provided invalid information in 3D Secure popup)
EXAMPLE CHECKOUT REQUEST (with charge)
{
"charge" : {
"amount" : 499,
"currency" : "USD"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"rememberMe" : true
}
EXAMPLE CHECKOUT REQUEST (with subscription)
{
"subscription" : {
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"rememberMe" : true
}
EXAMPLE CHECKOUT REQUEST (with custom charge)
{
"customCharge" : {
"amountOptions" : [100, 200, 500, 1000, 2000],
"customAmount" : {
"min" : 100,
"max" : 5000
},
"currency":"USD"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"rememberMe" : true
}
Signing a Checkout Request
Checkout Request signature is created using HMAC with SHA256 using Checkout Request JSON and your secret key. A signed Checkout Request is created by concatenating the signature, pipe character (|
), and Checkout Request JSON and then encoding it with BASE64.
The complete formula for signing Checkout Request:
$signed_checkout_request = base64( hmac_sha256( $checkout_request, $private_key ) + "|" + $checkout_request )
EXAMPLE SIGNING
export checkout_request='{"charge":{"amount":499,"currency":"USD"}}'
export signature=`echo -n "$checkout_request" | openssl dgst -sha256 -hmac 'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa' | sed 's/^.* //'`
echo -n "$signature|$checkout_request" | base64
EXAMPLE SIGNED CHECKOUT REQUEST
ODViMmQ1NWEwYmNkZmMxZTI5ZTAwOGYzZDdlODhhYmRkNGQzOGUyMjE4NjU4NjA2MjkzYjk1ZDA2ZWNkMzk4Y3x7ImNoYXJnZSI6eyJhbW91bnQiOjQ5OSwiY3VycmVuY3kiOiJVU0QifX0=
Credits
Credit represents funds transferred to a card.
Credit object
Attributes
id | string
created | timestamp
objectType | string (value is always "credit")
amount | integer, required
Credit amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
Credit currency represented as a three-letter ISO currency code.
description | string
card | card object
Card that was used to create this credit.
customerId | string
Identifier of the customer who is the owner of this credit or null
if this credit is not associated with any customer.
threeDSecureInfo | object
Additional data present if card used to create this credit was verified with 3D Secure. Can contain following attributes:
amount (integer) - amount in minor units that was used in 3D Secure
currency (string) - currency that was used in 3D Secure (represented as a three-letter ISO currency code)
enrolled (boolean) - information on whether the card used to create this charge supports 3D Secure
liabilityShift (string) - can have one of the following values:
pending
- 3D Secure was not started or is in progresssuccessful
- 3D Secure was completed successfullyfailed
- 3D Secure is supported, but was not completed successfullynot_possible
- 3D Secure is not supportedauthenticationFlow (string) - can have one of the following values:
frictionless
- Issuer authenticated the customer via the frictionless flow.challenge
- Issuer authenticated the customer by showing a challenge window.
receiver | object, optional
Can contain following attributes:
firstName (string)
lastName (string)
address (object) - address object, can contain the following attributes:
line1 (string)
line2 (string)
zip (string)
city (string)
state (string) - state or province. Required for the following countries: AU, CA, DE, US
country (string) - country represented as a two-letter ISO country code
merchantAccountId | string
Identifier of the merchant account that was used to create this credit.
metadata | metadata object
failureCode | string
Error code that describes why the credit has failed. Only present in failed credits. For the list of possible values see code
attribute in error object.
failureMessage | string
Human-readable message that describes why the credit has failed. Only present in failed credits.
failureIssuerDeclineCode | string
Code supplied by the issuer describing why the credit has failed.
fast | boolean
Indicates whether the credit has been made using the fast method.
EXAMPLE OBJECT
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "USD",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "202",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH",
"fastCredit" : {
"supported" : true,
"updated" : 1415811511
}
},
"customerId" : null,
"fast" : true,
"metadata" : {}
}
Create a new Credit
Creates a new credit object.
If you are in test mode, then provided card won't receive any funds, although everything else will work the same as in live mode.
Arguments
amount | integer, required
Credit amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string, required
Credit currency represented as a three-letter ISO currency code.
description | string, optional
customerId | string, optional (either customerId or card is required)
Identifier of the customer that will be associated with this credit. This field is required if the credit is being created with the customer's existing card. If specified, the successful charge created with the new card will add that card to the customer's cards and the card will be set as the default one.
card | card token, card details or card identifier, optional (either customerId or card is required)
Can be one of the following:
card token (for example obtained from Components)
card details (same as in card create request)
card identifier (must be an existing card that is associated with the customer specified in
customerId
field)
If the card is not provided, then the customer's default card will be used.
receiver | object, optional
Can contain following attributes:
firstName (string)
lastName (string)
address (object) - address object, can contain the following attributes:
line1 (string)
line2 (string)
zip (string)
city (string)
state (string) - state or province. Required for the following countries: AU, CA, DE, US
country (string) - country represented as a two-letter ISO country code
merchantAccountId | string, optional
Identifier of the merchant account that will be used to create this credit.
metadata | metadata object, optional
Result
A successful request returns a credit object that represents the created credit.
DEFINITION
POST https://api.shift4.com/credits
EXAMPLE REQUEST
curl https://api.shift4.com/credits \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=USD" \
-d "customerId=cust_AoR0wvgntQWRUYMdZNLYMz5R" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
-d "description=Example credit"
EXAMPLE RESPONSE
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "USD",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R"
}
Retrieve an existing Credit
Retrieves an existing credit object.
Arguments
CREDIT_ID | string, required
Identifier of the credit object that should be retrieved.
Result
A successful request returns a credit object.
DEFINITION
GET https://api.shift4.com/credits/{CREDIT_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/credits/cr_OwM7B3WWha5SIfjNSw2eUqVb \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "USD",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
Update an existing Credit
Update an existing credit object.
Any not provided parameter will be left unchanged.
Arguments
CREDIT_ID | string, required
Identifier of the credit object that should be updated.
customerId | string, required
Identifier of the customer that will be associated with this credit. Updating this field is only possible for the credit that is not assigned to any other customer. Assigning a successful credit to the customer will add the card used to create that credit to the customer's cards and will set this card as the customer's default one.
description | string, optional
metadata | metadata object, optional
Result
A successful request returns a credit object that was updated.
DEFINITION
POST https://api.shift4.com/credits/{CREDIT_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/credits/cr_OwM7B3WWha5SIfjNSw2eUqVb \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "description=New description"
EXAMPLE RESPONSE
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "USD",
"description" : "New description",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
List Credit
List credit objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
customerId | string, optional
Returns only credits associated with the given customer.
Result
A successful request returns a list of credit objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/credits
EXAMPLE REQUEST
curl "https://api.shift4.com/credits?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "USD",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
},
{ ... },
{ ... }
],
"hasMore" : true
}
Disputes
Dispute is created when a customer questions your charge with their bank or the credit card company. When this happens, you have an opportunity to respond by providing evidence that the charge is legitimate.
Dispute object
Attributes
id | string
created | timestamp
objectType | string (value is always "dispute")
updated | timestamp
amount | integer
Dispute amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
Dispute currency represented as a three-letter ISO currency code.
status | string
Current status of this dispute. Possible values are:
RETRIEVAL_REQUEST_NEW
- retrieval request, response neededRETRIEVAL_REQUEST_RESPONSE_UNDER_REVIEW
- retrieval request, response under reviewRETRIEVAL_REQUEST_REPRESENTED
- retrieval request, successfully representedCHARGEBACK_NEW
- chargeback, response neededCHARGEBACK_RESPONSE_UNDER_REVIEW
- chargeback, response under reviewCHARGEBACK_REPRESENTED_SUCCESSFULLY
- chargeback, dispute wonCHARGEBACK_REPRESENTED_UNSUCCESSFULLY
- chargeback, dispute lost
reason | string
Reason why customer created this dispute. Possible values are: FRAUDULENT
, UNRECOGNIZED
, DUPLICATE
, SUBSCRIPTION_CANCELED
, PRODUCT_NOT_RECEIVED
, PRODUCT_UNACCEPTABLE
, CREDIT_NOT_PROCESSED
, GENERAL
acceptedAsLost | boolean
Information on whether this dispute is closed and as a result of it, automatically lost.
charge | charge object
Charge associated with this dispute.
evidence | dispute evidence object
Evidence object that was created for this dispute.
evidenceDetails | object
Attributes:
hasEvidence (boolean)
submissionCount (integer)
dueBy (timestamp)
pastDue (boolean)
EXAMPLE OBJECT
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "USD",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "USD",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
Dispute Evidence object
Attributes
productDescription | string
A description of a product or service purchased by the customer including any details provided to the customer at the time of purchase.
customerName | string
The name of the customer.
customerEmail | string
Customer's email address provided during the purchasing process.
customerPurchaseIp | string
The IP address used by the customer while purchasing.
customerSignature | id of file upload
A scanned image or a photo of a document showing the customer's signature.
billingAddress | string
The billing address provided by the customer in the purchasing process.
receipt | id of file upload
Receipts and messages sent to the customer with the charge notification.
customerCommunication | id of file upload
Any communication with a customer that can help you win the dispute. These could be emails with proof of receiving the product or confirmation that the service was provided to the customer on the specified date.
serviceDate | string
The date on which a customer received the purchased service, displayed in a human-readable format.
serviceDocumentation | id of file upload
The documentation proving that the service was provided to the customer. It could be a copy of a signed contract, etc.
duplicateChargeId | string
The ID of the duplicated charge.
duplicateChargeDocumentation | id of file upload
Any documents with proof that there were two or more separated transactions. Include shipping details, receipt, packing list, etc.
duplicateChargeExplanation | string
Any information indicating that transactions were separated to prove that the prior charge wasn't duplicated.
refundPolicy | id of file upload
Your refund policy, as shown to the customer.
refundPolicyDisclosure | string
An explanation showing how and when the customer agreed to your refund policy.
refundRefusalExplanation | string
An explanation of why the customer is not entitled to a refund.
cancellationPolicy | id of file upload
Your subscription cancellation policy, as shown to the customer.
cancellationPolicyDisclosure | string
An explanation of how and when the customer agreed to your cancellation policy.
cancellationRefusalExplanation | string
An explanation showing that the customer continued using the product after the date they claimed to have stopped using it.
accessActivityLogs | id of file upload
Any evidence of the customer's activity after the date they claim to have cancelled the subscription, such as server or activity logs, IP addresses, etc.
shippingAddress | string
The shipping address to which a physical product was delivered. To maximize your chances of winning the dispute, the address should match a verified billing address.
shippingDate | string
The date on which a physical product began its route to the shipping address, displayed in a human-readable format and prior to the date of the dispute.
shippingCarrier | string
The name of the delivery service that shipped a physical product, eg. UPS, FedEx. If there are multiple carriers for the purchase, separate them with commas.
shippingTrackingNumber | string
The number given by the delivery service for a physical product. If there are multiple tracking numbers for one purchase, separate them with commas.
shippingDocumentation | id of file upload
Documentation with proof that cardholder received a product at the address provided in the purchasing process. This could be a document with the full shipping address, such as the shipment receipt, etc.
uncategorizedText | string
An explanation with further evidence that doesn't fit into any of the fields provided above.
uncategorizedFile | id of file upload
Any files or documents with further evidence that doesn't fit into any of the fields provided above.
EXAMPLE OBJECT
{
"productDescription" : null,
"customerName" : null,
"customerEmail" : null,
"customerPurchaseIp" : null,
"customerSignature" : null,
"billingAddress" : null,
"receipt" : null,
"customerCommunication" : null,
"serviceDate" : null,
"serviceDocumentation" : null,
"duplicateChargeId" : null,
"duplicateChargeDocumentation" : null,
"duplicateChargeExplanation" : null,
"refundPolicy" : null,
"refundPolicyDisclosure" : null,
"refundRefusalExplanation" : null,
"cancellationPolicy" : null,
"cancellationPolicyDisclosure" : null,
"cancellationRefusalExplanation" : null,
"accessActivityLogs" : null,
"shippingAddress" : null,
"shippingDate" : null,
"shippingCarrier" : null,
"shippingTrackingNumber" : null,
"shippingDocumentation" : null,
"uncategorizedText" : null,
"uncategorizedFile" : null
}
Retrieve an existing Dispute
Retrieves an existing dispute object.
Arguments
DISPUTE_ID | string, required
Identifier of the dispute object that should be retrieved.
Result
A successful request returns a dispute object.
DEFINITION
GET https://api.shift4.com/disputes/{DISPUTE_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "USD",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "USD",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
Update an existing Dispute
Updates an existing dispute object.
Any not provided parameter will be left unchanged.
Arguments
DISPUTE_ID | string, required
Identifier of the dispute object that should be updated.
submit | boolean, optional (default is true)
If true evidence would be submitted for review.
evidence | dispute evidence object, optional
Updating any attribute in evidence will submit all fields for review, unless submit=false
is specified. Can have following attributes:
productDescription (string, optional)
customerName (string, optional)
customerEmail (string, optional)
customerPurchaseIp (string, optional)
customerSignature (string, optional) - id of file upload
billingAddress (string, optional)
receipt (string, optional) - id of file upload
customerCommunication (string, optional) - id of file upload
serviceDate (string, optional)
serviceDocumentation (string, optional) - id of file upload
duplicateChargeId (string, optional) - id of charge
duplicateChargeDocumentation (string, optional) - id of file upload
duplicateChargeExplanation (string, optional)
refundPolicy (string, optional) - id of file upload
refundPolicyDisclosure (string, optional)
refundRefusalExplanation (string, optional)
cancellationPolicy (string, optional) - id of file upload
cancellationPolicyDisclosure (string, optional)
cancellationRefusalExplanation (string, optional)
accessActivityLogs (string, optional) - id of file upload
shippingAddress (string, optional)
shippingDate (string, optional)
shippingCarrier (string, optional)
shippingTrackingNumber (string, optional)
shippingDocumentation (string, optional) - id of file upload
uncategorizedText (string, optional)
uncategorizedFile (string, optional) - id of file upload
Result
Successful request returns a dispute object.
DEFINITION
POST https://api.shift4.com/disputes/{DISPUTE_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "evidence[productDescription]=Exclusive black shoes" \
-d "evidence[customerCommunication]=file_2nayTQXBBjaVEPVtCwGCbqOj"
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "USD",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "USD",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
Close an existing Dispute
Closing the dispute indicates that you do not want to submit any further evidence and acknowledge it as lost.
Arguments
DISPUTE_ID | string, required
Identifier of the dispute object that should be closed.
Result
A successful request returns identifier of the closed dispute object.
DEFINITION
POST https://api.shift4.com/disputes/{DISPUTE_ID}/close
EXAMPLE REQUEST
curl https://api.shift4.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj/close \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X POST
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "USD",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "USD",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
List Disputes
Lists dispute objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
Result
A successful request returns list of a dispute object.
DEFINITION
GET https://api.shift4.com/disputes
EXAMPLE REQUEST
curl https://api.shift4.com/disputes \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list": [{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "USD",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "USD",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2028",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}]
}
File Uploads
File Upload objects are created by uploading a binary file (like an image or PDF document) to Shift4. Such an uploaded file can then be used in other API requests by providing its identifier.
Note that for the file upload API a different API endpoint must be used: https://uploads.api.shift4.com.
File Upload object
Attributes
id | string
created | timestamp
objectType | string (value is always "file_upload")
purpose | string
Purpose of this file object. Possible values are: dispute_evidence
.
size | integer
Size of uploaded file in bytes.
type | string
Type of this file object. Possible values are: pdf
, jpg
, png
.
url | string
Read-only URL from which this file can be downloaded.
EXAMPLE RESPONSE
{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}
Create a File Upload
Creates a new file upload object.
Arguments
file | multipart file, required
File size should not exceed 8MB (8388608 bytes).
purpose | string, required
Purpose of this file object. Possible values are: dispute_evidence
Result
A successful request returns a file upload object that represents the uploaded file.
DEFINITION
POST https://uploads.api.shift4.com/files
EXAMPLE REQUEST
curl https://uploads.api.shift4.com/files \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-F "purpose=dispute_evidence" \
-F file="@example-file.jpg"
EXAMPLE RESPONSE
{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}
Retrieve an existing File Upload
Retrieves an existing file upload object.
Arguments
FILE_UPLOAD_ID | string, required
Identifier of the file upload object that should be retrieved.
Result
A successful request returns a file upload object.
DEFINITION
GET https://uploads.api.shift4.com/files/{FILE_UPLOAD_ID}
EXAMPLE REQUEST
curl https://uploads.api.shift4.com/files/file_2nayTQXBBjaVEPVtCwGCbqOj
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}
List File Uploads
Lists file upload objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
purpose | string, optional
Returns only file uploads with a given purpose.
Result
A successful request returns the list of a file upload object.
DEFINITION
GET https://uploads.api.shift4.com/files
EXAMPLE REQUEST
curl https://uploads.api.shift4.com/files?limit=2
EXAMPLE RESPONSE
{
"hasMore": false,
"list": [{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}]
}
Fraud Warnings
Fraud Warning represents information received from the card issuer regarding the charge.
Fraud Warning object
Attributes
id | string
created | timestamp
objectType | string (value is always "fraud_warning")
charge | charge object
Charge associated with this fraud warning.
actionable | boolean
Fraud warning is actionable if the associated charge is not fully refunded or disputed.
EXAMPLE OBJECT
{
"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
"created" : 1609325894,
"objectType" : "fraud_warning",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"actionable" : true
}
Retrieve an existing Fraud Warning
Retrieves an existing fraud warning object.
Arguments
FRAUD_WARNING_ID | string, required
Identifier of the fraud warning object that should be retrieved.
Result
A successful request returns a fraud warning object.
DEFINITION
GET https://api.shift4.com/fraud-warnings/{FRAUD_WARNING_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/fraud-warnings/fw_O7FRMgfC5g9BFqjEFepcB07J \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
"created" : 1609325894,
"objectType" : "fraud_warning",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"actionable" : true
}
List Fraud Warnings
Lists fraud warning objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
chargeId | string, optional
Identifier of the charge object for which fraud warnings should be listed.
actionable | boolean, optional
Can be used to list only actionable fraud warnings (see actionable in fraud warning object).
Result
A successful request returns a list of fraud-warning objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/fraud-warnings
EXAMPLE REQUEST
curl "https://api.shift4.com/fraud-warnings" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
"created" : 1609325894,
"objectType" : "fraud_warning",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"actionable" : true
},
{ ... },
{ ... }
],
"hasMore" : true
}
Payouts
Payout represents details of funds received from the acquirer. They are made on varying schedules, depending on your acquirer.
Payout object
Attributes
id | string
created | timestamp
objectType | string (value is always "payout")
amount | integer
Payout transfer amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
periodStart | timestamp
Timestamp of the payout period start.
periodEnd | timestamp
Timestamp of the payout period end.
currency | string
Payout transfer currency represented as a three-letter ISO currency code.
merchantAccountId | string, optional
Identifier of the merchant account that was used to create this payout.
EXAMPLE OBJECT
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "USD"
}
Retrieve an existing Payout
Retrieves an existing payout object.
Arguments
PAYOUT_ID | string, required
Identifier of the payout object that should be retrieved.
Result
A successful request returns a payout object.
DEFINITION
GET https://api.shift4.com/payouts/{PAYOUT_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/payouts/po_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "USD"
}
List Payouts
Lists payout objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
Result
A successful request returns a list of payout objects.
Results are sorted by payout date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/payouts
EXAMPLE REQUEST
curl "https://api.shift4.com/payouts?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "USD"
},
{ ... },
{ ... }
],
"hasMore" : true
}
Payout transaction object
Attributes
id | string
created | timestamp
objectType | string (value is always "payout_transaction")
type | string
Type of this transaction. Possible values are:
charge
refund
credit
chargeback
- disputed amount; exact definition may vary depending on the processorchargeback_represented
- disputed amount; exact definition may vary depending on the processorreserve_withhold
- amount witheld to a rolling reservereserve_release
- amount released to a rolling reserveacquirer_fee
- acquirer’s commissionadjustment
- fees not related to a rolling reserve, disputes or acquirer related fees, eg. custom contractual fees or card scheme related fees
amount | integer
Payout transaction amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
fee | integer
Payout transaction related fee sum in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".
currency | string
Payout transaction currency represented as a three-letter ISO currency code.
source (optional) | string
Related object id.
description (optional) | string
Additional info from the acquirer about the transaction.
exchangeRate (optional) | double
Exchange rate used when converting from transaction currency to payout currency.
EXAMPLE OBJECT
{
"id" : "pot_Y8x0X5d5zoRj6uI26vibFwkz",
"created" : 1604620800,
"objectType" : "payout_transaction",
"type" : "charge",
"amount" : 413,
"currency" : "USD",
"fee" : 39,
"source" : "char_1jmzPboimq0IDwz8zLXdX9qw",
"payout" : "po_gb48tN1UdWznKQHexcAAlbkK"
}
List Payout transactions
List payout transaction objects.
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
payout | string, optional if source argument present
Only transactions included in the payout will be returned
source | string, optional if payout argument present
Only transactions related to the source will be returned
Result
A successful request returns a list of payout transaction objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/payout-transactions
EXAMPLE REQUEST
curl "https://api.shift4.com/payout-transactions?payout=po_gb48tN1UdWznKQHexcAAlbkK" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "pot_Y8x0X5d5zoRj6uI26vibFwkz",
"created" : 1604620800,
"objectType" : "payout_transaction",
"type" : "charge",
"amount" : 413,
"currency" : "USD",
"fee" : 39,
"source" : "char_1jmzPboimq0IDwz8zLXdX9qw",
"payout" : "po_gb48tN1UdWznKQHexcAAlbkK"
},
{ ... },
{ ... }
],
"hasMore" : true
}
Create a Test Payout
Creates test Payout based on test mode charges, refunds, chargebacks and credits.
Result
A successful request returns payout object.
DEFINITION
POST https://api.shift4.com/payouts
EXAMPLE REQUEST
curl -X POST "https://api.shift4.com/payouts" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "USD"
}
Payment Method
Payment Method represents an alternative payment method different from the card payments.
Payment Methods object can be used to define details of the payment method that will be used during payments.
Payment Method object
Attributes
id | string
created | timestamp
objectType | string (value is always "payment_method")
clientObjectId | string
Public identifier of the Payment Method that allows to securely access the object from client frontend code without exposing any sensitive data
customerId | string
Identifier of the customer that is the owner of this payment method.
type | string
The type of the payment method. For the selected payment method type it will be alipay
status | string
Status of payment method.
Possible values are:
chargeable
- Payment Method is ready to be used to create a charge.pending
- Payment Method setup process is in progress.failed
- setup process of the Payment Method failed.used
- payment method was already charged and cannot be reused.
billing | object
Billing details. Can contain the following attributes:
name (string) - name of billed person or company
email (string) - email of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a wo-letter ISO country code
phone (string) - phone of billed person or company
vat (string) - tax identification number
fraudCheckData | object
Additional data used for fraud protection. Can contain the following attributes:
ipAddress (string) - IP address of the user
ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)
email (string) - e-mail address of the user
phone (string) - phone number of the user
userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token
merchantAccountId | string
Identifier of the merchant account that was used to create this charge.
metadata | metadata object, optional
EXAMPLE OBJECT
{
"id" : "pm_BokS87jDShjASDkjhdsak4kl",
"created" : 1415810511,
"objectType" : "payment_method",
"clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
"customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
"type" : "alipay",
"status" : "chargeable",
"billing" : {
"name" : "Werner Heisenberg",
"address" : {
"country" : "CN"
}
}
}
Create a new Payment Method
Arguments
type | string, required
The type of the payment method. Should have value: alipay
customerId | string, optional
Identifier of the customer that will be associated with this payment method.
merchantAccountId | string, optional
Identifier of the merchant account that will be used to create this payment method.
billing | object
Billing details. Can contain the following attributes:
name (string, required) - name of billed person or company
email (string) - email of billed person or company
address (object) - address object, can contain the following attributes:
line1 (string) - address first line
line2 (string) - address second line
zip (string) - ZIP (postal) code
city (string) - city or town
state (string) - state or province
country (string) - country represented as a two-letter ISO country code
vat (string) - tax identification number
fraudCheckData | object, optional
Additional data used for fraud protection. Can contain the following attributes:
ipAddress - IP address of the user
ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)
email (string) - e-mail address of the user
phone (string) - phone number of the user, eg. +12345678901
userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token
metadata | metadata object, optional
Result
A successful request returns a payment method object that represents the created payment method.
DEFINITION
POST https://api.shift4.com/payment-methods
EXAMPLE REQUEST
curl -X POST 'https://api.shift4.com/payment-methods' \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d 'type=alipay' \
-d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
-d 'billing.address.country=CN' \
-d 'billing.name=Werner Heisenberg'
EXAMPLE RESPONSE
{
"id" : "pm_BokS87jDShjASDkjhdsak4kl",
"created" : 1415810511,
"objectType" : "payment_method",
"clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
"customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
"type" : "alipay",
"status" : "chargeable",
"billing" : {
"name" : "Werner Heisenberg",
"address" : {
"country" : "CN"
}
}
}
Retrieve an existing Payment Method
Retrieves an existing payment method object.
Arguments
PAYMENT_METHOD_ID | string, required
Identifier of the payment method object that should be retrieved.
Result
A successful request returns a payment method object.
DEFINITION
GET https://api.shift4.com/payment-methods/{PAYMENT_METHOD_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/payment-methods/pm_8HeqP7ZurLKhBPknC5e6sR85 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "pm_BokS87jDShjASDkjhdsak4kl",
"created" : 1415810511,
"objectType" : "payment_method",
"clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
"customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
"type" : "alipay",
"status" : "chargeable",
"billing" : {
"name" : "Werner Heisenberg",
"address" : {
"country" : "CN"
}
}
}
Delete a Payment Method
Deletes an existing payment method object.
If you delete the payment method that is set as the default one, then the most recently added payment method will be used as the new default payment method.
If you delete the last payment method then the default payment method will be set to null
and, if present, the most recently added card will be set as the default card.
Arguments
PAYMENT_METHOD | string, required
Identifier of the payment method object that should be deleted.
Result
A successful request returns identifier of the deleted payment method object.
DEFINITION
DELETE https://api.shift4.com/payment-methods/{PAYMENT_METHOD_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/payment-methods/pm_8HeqP7ZurLKhBPknC5e6sR85 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "pm_8P7OWXA5xiTS1ISnyZcum1KV"
}
List Payment Methods
Lists payment method objects for a given customer.
Arguments
customerId | string, required
Identifier of the customer object whose payment methods should be listed.
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
deleted | boolean, optional (default is false)
Can be used to list deleted objects.
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list.
Result
A successful request returns a list of payment method objects.
Results are sorted by creation date, with the most recent objects first.
DEFINITION
GET https://api.shift4.com/payment-methods
EXAMPLE REQUEST
curl "https://api.shift4.com/payment-methods?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "pm_BokS87jDShjASDkjhdsak4kl",
"created" : 1415810511,
"objectType" : "payment_method",
"clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
"customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
"type" : "alipay",
"status" : "chargeable",
"billing" : {
"name" : "Werner Heisenberg",
"address" : {
"country" : "CN"
}
}
},
{ ... },
{ ... }
],
"hasMore" : false
}
Payment Links
Payment Links is a functionality that allows you to create an URL with a simple checkout. Customers that enter this link are able to either make a single payment or initialize a subscription without visiting the merchant's webpage.
Payment link object
Arguments
id | string
created | timestamp
status | string
Status of a Payment link.
It can be one of the following:
active
- Payment link is active and functionalexpired
- Payment link expired and is no longer functionaldeactivated
- Payment link has been deactivated by merchantcompleted
- preset number of successful charges made with this payment link has been reached, it is no longer functionalscheduled
- Payment link is yet to become active
url | string
lineItems | list of objects
A list of objects created with the payment link. It can be one of two types:
product - object representing a single charge made through checkout generated by the Payment link
name
amount - amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".
currency - currency represented as a three-letter ISO currency code.
subscription
plan - planId used to create a subscription
collectBillingAddress | boolean
If the value is true, the customer will be asked to provide the billing address.
collectShippingAddress | boolean
If the value is true, the customer will be asked to provide the shipping address.
restrictions | object
This object describes time boundaries and preset number of charges made with the Payment link
charges - fields limit number of successful attempts to use the Payment link and presents how many successful attempts there were
limit (integer) - number of preset attempts
count (integer) - number of successful charges
customer | string
Customer associated with the charge or subscription created via the Payment link.
metadata | metadata object
Result
A successful request returns a Payment Link object.
EXAMPLE OBJECT
{
"id" : "link_8v6pz2FEOvlDA80wOGhUhP8N",
"created" : 1746021690,
"status" : "active",
"url" : "https://pay.shift4.com/link_8v6pz2FEOvlDA80wOGhUhP8N",
"lineItems" : [ {
"product" : {
"name" : "Single Payment",
"amount" : 100000,
"currency" : "PLN"
}
} ],
"collectBillingAddress" : true,
"collectShippingAddress" : false,
"restrictions" : {
"charges" : {
"limit" : 20,
"count" : 0
}
},
"metadata" : {
"invoiceNumber" : "INV_1206"
}
}
Create a new Payment link
Arguments
lineItems | list of objects, required
A list of objects created with the Payment link. It can be one of two types:
product - object representing a single charge made through checkout generated by the Payment link
name
amount - amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10"
currency - currency represented as a three-letter ISO currency code
subscription
plan - planId used to create a subscription
collectBillingAddress | boolean, optional (default is "false")
If the value is true, the customer will be asked to provide the billing address.
collectShippingAddress | boolean, optional (default is "false")
If the value is true, the customer will be asked to provide the shipping address.
restrictions | object, optional
This object describes time boundaries and preset number of charges made with the Payment link
charges - fields limit number of successful attempts to use the Payment link and presents how many successful attempts there were
limit (integer) - number of preset attempts
customer | string, optional
Customer associated with the charge or subscription created via the Payment link.
metadata | metadata object, optional
Result
A successful request returns a Payment Link object that represents the created Payment link.
DEFINITION
POST https://api.shift4.com/payment-links
EXAMPLE REQUEST
curl https://api.shift4.com/payment-links \
-u sk_test_xxxx: \
-H "Content-Type: application/json" \
--data-raw '{
"lineItems": [
{
"product": {
"name": "Example charge",
"amount": 1000,
"currency": "USD"
}
}
]
}'
EXAMPLE RESPONSE
{
"id" : "link_8kdskX8DZ8FR6W3acYPXiyAN",
"created" : 1747678041,
"status" : "active",
"url" : "https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN",
"lineItems" : [ {
"product" : {
"name" : "Example charge",
"amount" : 1000,
"currency" : "USD"
}
} ],
"collectBillingAddress" : false,
"collectShippingAddress" : false,
"customFields" : [ ],
"metadata" : { }
}
Retrieve an existing Payment link
Arguments
PAYMENT_LINK_ID | string, required
Result
A successful request returns a Payment Link object.
DEFINITION
GET https://api.shift4.com/payment-links/{PAYMENT_LINK_ID}
EXAMPLE REQUEST
curl https://api.shift4.com/payment-links/link_odedW8aombcWuu6VIZulYKny \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id": "link_odedW8aombcWuu6VIZulYKny",
"created": 1746025976,
"status": "active",
"url": "https://pay.shift4.com/link_odedW8aombcWuu6VIZulYKny",
"lineItems": [
{
"product": {
"plan": "plan_0i8adiW3GNKVC5UDsKjw6r8D"
}
}
],
"collectBillingAddress": true,
"collectShippingAddress": false,
"customer": "cust_jDgssNAb33TEYCjqkMh55NtF",
"metadata": {}
}
Update an existing Payment link
Arguments
PAYMENT_LINK_ID | string, required
lineItems | list of objects, required
A list of objects created with the Payment link. It can be one of two types:
product - object representing a single charge made through checkout generated by the Payment link
name
amount - amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10"
currency - currency represented as a three-letter ISO currency code
subscription
plan - planId used to create a subscription
collectBillingAddress | boolean, optional
If the value is true, the customer will be asked to provide the billing address.
collectShippingAddress | boolean, optional
If the value is true, the customer will be asked to provide the shipping address.
restrictions | object, optional
This object describes time boundaries and preset number of charges made with the Payment link
charges - fields limit number of successful attempts to use the payment link and presents how many successful attempts there were
limit (integer) - number of preset attempts
metadata | metadata object, optional
Result
A successful request returns a Payment Links object that represents the updated Payment link.
DEFINITION
POST https://api.shift4.com/payment-links/PAYMENT_LINK_ID
EXAMPLE REQUEST
curl https://api.shift4.com/payment-links/link_123RF3wsQ6Eeap9b7uF5URSr \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-H "Content-Type: application/json" \
--data-raw '{
"lineItems": [
{
"product": {
"amount": 1000,
"currency": "USD",
"name": "Another example charge"
}
}
],
"collectBillingAddress": true
}'
EXAMPLE RESPONSE
{
"id" : "link_123RF3wsQ6Eeap9b7uF5URSr",
"created" : 1747724812,
"status" : "active",
"url" : "https://pay.shift4.com/link_123RF3wsQ6Eeap9b7uF5URSr",
"lineItems" : [ {
"product" : {
"name" : "Another example charge",
"amount" : 1000,
"currency" : "USD"
}
} ],
"collectBillingAddress" : true,
"collectShippingAddress" : false,
"customFields" : [ ],
"metadata" : { }
Deactivate an existing Payment link
Arguments
PAYMENT_LINK_ID | string, required
Result
A successful request deactivates a Payment Link object.
DEFINITION
POST https://api.shift4.com/payment-links/PAYMENT_LINK_ID/deactivate
EXAMPLE REQUEST
curl https://api.shift4.com/payment-links/link_UctAU7n0JOWcHkmRyplafj3D/deactivate \
-u sk_test_wpjbb6WhmPkiosrwcOffQNPV: \
-X POST
EXAMPLE RESPONSE
{
"id": "link_UctAU7n0JOWcHkmRyplafj3D",
"created": 1727864053,
"status": "deactivated",
"url": "https://pay.shift4.com/link_UctAU7n0JOWcHkmRyplafj3D",
"lineItems": [
{
"product": {
"name": "Single payment",
"amount": 20000,
"currency": "USD"
}
}
],
"collectBillingAddress": true,
"collectShippingAddress": false,
"metadata": {}
}
Reactivate an existing Payment link
Arguments
PAYMENT_LINK_ID | string, required
Result
A successful request reactivates a Payment Link object.
DEFINITION
POST https://api.shift4.com/payment-links/PAYMENT_LINK_ID/reactivate
EXAMPLE REQUEST
curl https://api.shift4.com/payment-links/link_UctAU7n0JOWcHkmRyplafj3D/reactivate \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X POST
EXAMPLE RESPONSE
{
"id": "link_UctAU7n0JOWcHkmRyplafj3D",
"created": 1727864053,
"status": "active",
"url": "https://pay.shift4.com/link_UctAU7n0JOWcHkmRyplafj3D",
"lineItems": [
{
"product": {
"name": "Single payment",
"amount": 20000,
"currency": "USD"
}
}
],
"collectBillingAddress": true,
"collectShippingAddress": false,
"metadata": {}
}
List Payment links
Arguments
created | object, optional
Filter results based on value of created
attribute. Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestamp
limit | integer, optional (default is 10)
Limits the number of returned objects. The limit must be between 1 and 100.
startingAfterId | string, optional
Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get the next page of that list.
endingBeforeId | string, optional
Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get the previous page of that list
status | string, optional
Status of a payment link.
It can be one of the following:
active
- Payment link is active and functionalexpired
- Payment link expired and is no longer functionaldeactivated
- Payment link has been deactivated by merchantcompleted
- preset number of successful charges made with this Payment link has been reached, it is no longer functionalscheduled
- Payment link is yet to become active
Result
A successful request returns a list of Payment Link objects.
DEFINITION
GET https://api.shift4.com/payment-links/payment-links
EXAMPLE REQUEST
curl "https://api.shift4.com/payment-links?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [ {
"id" : "link_123RF3wsQ6Eeap9b7uF5URSr",
"created" : 1747724812,
"status" : "active",
"url" : "https://pay.shift4.com/link_123RF3wsQ6Eeap9b7uF5URSr",
"lineItems" : [ {
"product" : {
"name" : "Another example charge",
"amount" : 1000,
"currency" : "USD"
}
} ],
"collectBillingAddress" : true,
"collectShippingAddress" : false,
"customFields" : [ ],
"metadata" : { }
}, {
"id" : "link_8kdskX8DZ8FR6W3acYPXiyAN",
"created" : 1747678041,
"status" : "active",
"url" : "https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN",
"lineItems" : [ {
"product" : {
"name" : "Example charge",
"amount" : 1000,
"currency" : "USD"
}
} ],
"collectBillingAddress" : false,
"collectShippingAddress" : false,
"customFields" : [ ],
"metadata" : { }
}, {
"id" : "link_odedW8aombcWuu6VIZulYKny",
"created" : 1746025976,
"status" : "active",
"url" : "https://pay.shift4.com/link_odedW8aombcWuu6VIZulYKny",
"lineItems" : [ {
"product" : {
"plan" : "plan_0i8adiW3GNKVC5UDsKjw6r8D"
}
} ],
"collectBillingAddress" : true,
"collectShippingAddress" : false,
"customer" : "cust_jDgssNAb33TEYCjqkMh55NtF",
"customFields" : [ ],
"metadata" : { }
} ],
"hasMore" : true
}
Checkout session details
The checkout session contains data related to a single session and maintains a reference to the charge executed within that session, along with information regarding the success of the charge. Payment link can be associated with several sessions depending on the preset limit.
Arguments
CHARGE_ID | string, required
DEFINITION
GET https://api.shift4.com/payment-links/payment-links/checkout-sessions?charge={CHARGE_ID}
EXAMPLE REQUEST
curl "https://api.shift4.com/checkout-sessions?charge=char_qTTjFTmM6uBFHrHts9gga8Ri" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list": [
{
"id": "chse_wo7mzgRKMEBk21ChHLMcL8ph",
"created": 1747726145,
"objectType": "checkout_session",
"lastCharge": "char_qTTjFTmM6uBFHrHts9gga8Ri",
"paymentLink": "link_8kdskX8DZ8FR6W3acYPXiyAN"
}
],
"totalCount": 1,
"hasMore": false
}