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 parameters
card_error - Card processing has failed
gateway_error - Something went wrong on our side
rate_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:
invalid_number - The card number is not a valid one.
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.
incorrect_zip - The card's zip code 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.
limit_exceeded - You have exceeded the defined limit.
card_declined - The card was declined for another reason.
processing_error - An error occurred while processing the card.
blacklisted - The card has been blacklisted.
expired_token - The token has expired.
authentication_required - The charge requires authentication.
do_not_try_again - The card was declined and should not be retried.
currency_not_supported - Your account is not configured to process the given currency.
brand_not_supported - The card brand is not supported.

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 successfully
pending - payment is being processed, see the flow 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 the flow.redirect.redirectUrl
- wait - payment is being processed, wait for flow.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 or fraudulent
score (integer) - the percentage chance that the charge is fraudulent

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:
pending - 3D Secure was not started or is in progress
successful - 3D Secure was completed successfully
failed - 3D Secure is supported, but was not completed successfully
not_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 matched
partial_match - Some address elements matched
no_match - No address element matched
not_provided - Address not provided
unavailable - Address verification service was unavailable

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" : "2027",
	  "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" : {}
}

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 incustomerId 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

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
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.

metadata metadata object, optional

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"

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,

}

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" : "2027",
	  "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

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
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 or unknown

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" : "2027",
	  "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" : "2027",
	  "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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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 charges associated with a given customer.

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" : "2027",
			  "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
}

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

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

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

Retrieves an existing refund object.

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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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" : "2027",
      "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" : "2027",
      "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" : "2027",
      "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" : "2027",
      "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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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" : "2027",
		      "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" : "2027",
  "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
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" : "2027",
  "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" : "2027",
  "cardholderName" : "John Doe",
  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "brand" : "Visa",
  "type" : "Credit Card",
  "issuer" : "Card Issuer Name",
  "country" : "CH"
}

Update an existing Card

Update an existing card object.

Any not provided parameter will be left unchanged.

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 string, optional

Card expiration month.

expYear string, optional

Card expiration year.

cardholderName string, optional

addressCountry string, optional

Country represented as a three-letter ISO country code.

addressCity string, optional

addressState string, optional

addressZip string, optional

addressLine1 string, optional

addressLine2 string, optional

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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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" : "2027",
		  "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 period
active - subscription is active and will be renewed after the end of a current billing cycle
past_due - renewing of subscription has failed
canceled - subscription was manually canceled, or all retry renewal attempts have failed
unpaid - all retry renewal attempts have failed
incomplete - 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

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
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

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
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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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?limit=3" \
	-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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

Result

A successful request returns a list of plan objects.

Results are sorted by creation date, with the most recent objects first.

DEFINITION


GET https://api.shift4.com/plans

EXAMPLE REQUEST


curl "https://api.shift4.com/plans?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

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" : "2027",
		  "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" : "2027",
			  "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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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" : "2027",
				  "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.

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 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

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:
pending - 3D Secure was not started or is in progress
successful - 3D Secure was completed successfully
failed - 3D Secure is supported, but was not completed successfully
not_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.

EXAMPLE OBJECT

{
  "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" : true,
  "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"
  }
}

Create a new Token

Creates a new token object.

This method can be called with either "API Public Key" or "API Secret Key".

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 three-letter ISO country code.

fraudCheckData object

Additional data used for fraud protection. Can contain 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
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=2027" \
	-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 to true
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 or failed

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)

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]=2027" \
	-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": "2027",
		"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",
}

List Blacklist Rules

Lists blacklist rule objects.

Arguments

created object, optional

Filter results based on value of created attribute. Can have following attributes:

gt - return objects created after given timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

Result

A successful request returns a list of blacklist rule objects.

Results are sorted by creation date, with the most recent objects first.

DEFINITION


GET https://api.shift4.com/blacklist

EXAMPLE REQUEST


curl "https://api.shift4.com/blacklist?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
			"created" : 1429282784,
			"objectType" : "blacklistRule",
			"ruleType" : "fingerprint",
			"fingerprint" : "e3d8suyIDgFg3pE7"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

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 and max 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.

rememberMe boolean, optional, default is false

"Remember-me" option possible to be preselected in Checkout.

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.

This feature is available for selected business models only. Please contact [email protected] to find out more.

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 progress
successful - 3D Secure was completed successfully
failed - 3D Secure is supported, but was not completed successfully
not_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.

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" : "2027",
	  "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.

This feature is available for selected business models only. Please contact [email protected] to find out more.

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" : "2027",
	  "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.

This feature is available for selected business models only. Please contact [email protected] to find out more.

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" : "2027",
	  "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.

This feature is available for selected business models only. Please contact [email protected] to find out more.

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" : "2027",
	  "cardholderName" : "John Doe",
	  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	  "brand" : "Visa",
	  "type" : "Credit Card",
	  "issuer" : "Card Issuer Name",
	  "country" : "CH"
	}
}

List Credit

List credit objects.

This feature is available for selected business models only. Please contact [email protected] to find out more.

Arguments

created object, optional

Filter results based on value of created attribute. Can have following attributes:

gt - return objects created after given timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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" : "2027",
			  "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 needed
RETRIEVAL_REQUEST_RESPONSE_UNDER_REVIEW - retrieval request, response under review
RETRIEVAL_REQUEST_REPRESENTED - retrieval request, successfully represented
CHARGEBACK_NEW - chargeback, response needed
CHARGEBACK_RESPONSE_UNDER_REVIEW - chargeback, response under review
CHARGEBACK_REPRESENTED_SUCCESSFULLY - chargeback, dispute won
CHARGEBACK_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 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" : "2027",
		  "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.

customer Name 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 RESPONSE


{
	"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" : "2027",
		  "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

Size sum of all file uploads in evidence cannot exceed 8,2MB.

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" : "2027",
		  "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" : "2027",
		  "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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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" : "2027",
			  "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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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, chargeback_represented, reserve_withhold, reserve_release, acquirer_fee or adjustment.

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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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 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

Show details for payment method:

Attributes

id string

created timestamp

objectType string (value is always "payment_method")

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 alipayapple_paybancontactbitpayblikboletoepsestonianbanksgoogle_payideallatvianbankslithuanianbanksmaximamultibancomybankp24paypostpaysafecardpaysafecashpayserapayuperlasskrillthree_d_securetrustlyunionpayverkkopankkiwechatpay

status 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.

applePay object

Details specific to payment method of type apple_pay. Can contain the following attributes:

amount (integer) - amount for which Apple Pay token was created
currency (string) - currency for which Apple Pay token was created
first6 (string) - first 6 numbers of device-specific account number of the card used in Apple Pay
last4 (string) - last 4 numbers of device-specific account number of the card used in Apple Pay
cardBrand (string) - brand of the card used in Apple Pay. Possible values are: Visa,American Express,MasterCard,Discover,JCB,Diners Club,Unknown
cardType (string) - type of the card used in Apple Pay. Possible values are: Credit Card,Debit Card,Unknown

googlePay object

Details specific to payment method of type google_pay. Can contain the following attributes:

first6 (string) - first 6 numbers of device-specific account number of the card used in Apple Pay
last4 (string) - last 4 numbers of device-specific account number of the card used in Apple Pay
cardBrand (string) - brand of the card used in Google Pay™. Possible values are: Visa,American Express,MasterCard,Discover,JCB,Diners Club,Unknown
cardType (string) - type of the card used in Google Pay™. Possible values are: Credit Card,Debit Card,Unknown

source object

Full Payment Method Object that was used as source for three_d_secure Payment Method. At the moment only supported source is Payment Method of type google_pay.

threeDSecure object

amount (integer) - amount for which ThreeDSecure was created

currency (string) - currency for which ThreeDSecure was created

flow object

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:
- three_d_secure - three_d_secure has to be perform on this Payment Method
- none

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"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "apple_pay",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "applePay" : {
    "first6" : "424242",
    "last4" : "4242",
    "amount" : 1000,
    "currency" : "USD"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "bancontact",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "BE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "bitpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "blik",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "PL"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "boleto",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "BR"
    },
    "vat" : "999.999.999-99",
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "eps",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "estonianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "EE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "google_pay",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "googlePay" : {
    "cardBrand" : "Visa",
    "cardType" : "Debit Card",
    "first6" : "424242",
    "last4" : "4242"
  },
  "flow" : {
    "nextAction" : "none"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "ideal",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "NL"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "latvianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LV"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "lithuanianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "maxima",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "multibanco",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "PT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "mybank",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "IT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "p24",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "PL"
    },
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paypost",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysafecard",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysafecash",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysera",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "EE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "payu",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "CZ"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "perlas",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "skrill",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "three_d_secure",
  "status" : "pending",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "threeDSecure" : {
    "amount" : 1000,
    "currency" : "USD"
  },
  "source" : {
    "id" : "pm_BokS87jDShjASDkjhdsak4kl",
    "created" : 1415810511,
    "objectType" : "payment_method",
    "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
    "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
    "type" : "google_pay",
    "status" : "chargeable",
    "billing" : {
      "address" : {
        "country" : "US"
      }
    },
    "googlePay" : {
      "cardBrand" : "Visa",
      "cardType" : "Debit Card",
      "first6" : "424242",
      "last4" : "4242"
    },
    "flow" : {
      "nextAction" : "none"
    }
  },
  "flow" : {
    "nextAction" : "three_d_secure"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "trustly",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "unionpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    },
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "verkkopankki",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "FI"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "wechatpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "CN"
    }
  }
}

Create a new Payment Method

Creates a new payment method object.

Show details for the payment method:

Arguments

type

string, required

The type of the payment method. Should have value: alipayapple_paybancontactbitpayblikboletoepsestonianbanksgoogle_payideallatvianbankslithuanianbanksmaximamultibancomybankp24paypostpaysafecardpaysafecashpayserapayuperlasskrillthree_d_securetrustlyunionpayverkkopankkiwechatpay

customerId

string, required

Identifier of the customer that will be associated with this payment method.

applePay

object, required

Details specific to payment method of type apple_pay. Can contain the following attributes:

token (object, required) - Apple Pay token

googlePay

object, required

Details specific to payment method of type google_pay. Can contain the following attributes:

token (string, required) - Google Pay™ token

three_d_secure

object, required

Details specific to payment method of type three_d_secure. Can contain the following attributes:

amount (integer, required) - amount in minor units of a given currency
currency (string, required) - currency represented as a three-letter ISO currency code

source

string, required

Identifier of the Payment Method that will be a source of data for the 3DS process. Source Payment Method has to be of type google_pay

merchantAccountId string, optional

Identifier of the merchant account that will be used to create this payment method.

billing

object, required

Billing details. Can contain the following attributes:

name (string, required) - name of billed person or company
email (string, required) - 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, required) - tax identification number: CPF or CNPJ

fraudCheckData object

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
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'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=apple_pay' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=US' \
  -d 'applePay.token={ "data": "TEST_TOKEN:1000USD" }'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=bancontact' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=BE'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=bitpay' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=US' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=blik' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=PL' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=boleto' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=BR' \
  -d 'billing.name=Werner Heisenberg' \
  -d '[email protected]' \
  -d 'billing.vat=999.999.999-99'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=eps' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=AT'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=estonianbanks' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=EE' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=google_pay' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=US' \
  -d 'googlePay.token=PAN_ONLY'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=ideal' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=NL'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=latvianbanks' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=LV' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=lithuanianbanks' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=LT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=maxima' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=LT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=multibanco' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=PT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=mybank' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=IT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=p24' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=PL' \
  -d '[email protected]'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=paypost' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=LT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=paysafecard' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=AT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=paysafecash' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=AT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=paysera' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=EE' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=payu' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=CZ' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=perlas' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=LT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=skrill' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=US' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=three_d_secure' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=US' \
  -d 'source=pm_aokF87jdbkjCADkihesRk1kX' \
  -d 'threeDSecure.amount=1000' \
  -d 'threeDSecure.currency=USD'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=trustly' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=AT' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=unionpay' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=US' \
  -d 'billing.name=Werner Heisenberg' \
  -d '[email protected]'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=verkkopankki' \
  -d 'customerId=cust_BokS87jDShjASDkjhdsak4kl' \
  -d 'billing.address.country=FI' \
  -d 'billing.name=Werner Heisenberg'

curl -X POST 'https://api.shift4.com/payment-methods' \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d 'type=wechatpay' \
  -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"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "apple_pay",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "applePay" : {
    "first6" : "424242",
    "last4" : "4242",
    "amount" : 1000,
    "currency" : "USD"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "bancontact",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "BE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "bitpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "blik",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "PL"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "boleto",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "BR"
    },
    "vat" : "999.999.999-99",
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "eps",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "estonianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "EE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "google_pay",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "googlePay" : {
    "cardBrand" : "Visa",
    "cardType" : "Debit Card",
    "first6" : "424242",
    "last4" : "4242"
  },
  "flow" : {
    "nextAction" : "none"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "ideal",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "NL"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "latvianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LV"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "lithuanianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "maxima",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "multibanco",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "PT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "mybank",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "IT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "p24",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "PL"
    },
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paypost",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysafecard",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysafecash",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysera",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "EE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "payu",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "CZ"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "perlas",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "skrill",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "three_d_secure",
  "status" : "pending",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "threeDSecure" : {
    "amount" : 1000,
    "currency" : "USD"
  },
  "source" : {
    "id" : "pm_BokS87jDShjASDkjhdsak4kl",
    "created" : 1415810511,
    "objectType" : "payment_method",
    "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
    "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
    "type" : "google_pay",
    "status" : "chargeable",
    "billing" : {
      "address" : {
        "country" : "US"
      }
    },
    "googlePay" : {
      "cardBrand" : "Visa",
      "cardType" : "Debit Card",
      "first6" : "424242",
      "last4" : "4242"
    },
    "flow" : {
      "nextAction" : "none"
    }
  },
  "flow" : {
    "nextAction" : "three_d_secure"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "trustly",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "unionpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    },
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "verkkopankki",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "FI"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "wechatpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "CN"
    }
  }
}

Retrieve an existing Payment Method

Retrieves an existing payment method object.

Shows an example response for the payment method:

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"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "apple_pay",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "applePay" : {
    "first6" : "424242",
    "last4" : "4242",
    "amount" : 1000,
    "currency" : "USD"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "bancontact",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "BE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "bitpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "blik",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "PL"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "boleto",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "BR"
    },
    "vat" : "999.999.999-99",
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "eps",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "estonianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "EE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "google_pay",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "googlePay" : {
    "cardBrand" : "Visa",
    "cardType" : "Debit Card",
    "first6" : "424242",
    "last4" : "4242"
  },
  "flow" : {
    "nextAction" : "none"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "ideal",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "NL"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "latvianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LV"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "lithuanianbanks",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "maxima",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "multibanco",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "PT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "mybank",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "IT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "p24",
  "status" : "chargeable",
  "billing" : {
    "address" : {
      "country" : "PL"
    },
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paypost",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysafecard",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysafecash",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "paysera",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "EE"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "payu",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "CZ"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "perlas",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "LT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "skrill",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "three_d_secure",
  "status" : "pending",
  "billing" : {
    "address" : {
      "country" : "US"
    }
  },
  "threeDSecure" : {
    "amount" : 1000,
    "currency" : "USD"
  },
  "source" : {
    "id" : "pm_BokS87jDShjASDkjhdsak4kl",
    "created" : 1415810511,
    "objectType" : "payment_method",
    "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
    "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
    "type" : "google_pay",
    "status" : "chargeable",
    "billing" : {
      "address" : {
        "country" : "US"
      }
    },
    "googlePay" : {
      "cardBrand" : "Visa",
      "cardType" : "Debit Card",
      "first6" : "424242",
      "last4" : "4242"
    },
    "flow" : {
      "nextAction" : "none"
    }
  },
  "flow" : {
    "nextAction" : "three_d_secure"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "trustly",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "AT"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "unionpay",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "US"
    },
    "email" : "[email protected]"
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "verkkopankki",
  "status" : "chargeable",
  "billing" : {
    "name" : "Werner Heisenberg",
    "address" : {
      "country" : "FI"
    }
  }
}

{
  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
  "created" : 1415810511,
  "objectType" : "payment_method",
  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
  "type" : "wechatpay",
  "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.

Show example response for payment method:

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 timestamp
gte - return objects created after or exactly on given timestamp
lt - return objects created before given timestamp
lte - 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

endingBeforeId string, optional

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
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "apple_pay",
		  "status" : "chargeable",
		  "billing" : {
		    "address" : {
		      "country" : "US"
		    }
		  },
		  "applePay" : {
		    "first6" : "424242",
		    "last4" : "4242",
		    "amount" : 1000,
		    "currency" : "USD"
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "bancontact",
		  "status" : "chargeable",
		  "billing" : {
		    "address" : {
		      "country" : "BE"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "bitpay",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "US"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "blik",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "PL"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "boleto",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "BR"
		    },
		    "vat" : "999.999.999-99",
		    "email" : "[email protected]"
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "eps",
		  "status" : "chargeable",
		  "billing" : {
		    "address" : {
		      "country" : "AT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "estonianbanks",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "EE"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "google_pay",
		  "status" : "chargeable",
		  "billing" : {
		    "address" : {
		      "country" : "US"
		    }
		  },
		  "googlePay" : {
		    "cardBrand" : "Visa",
		    "cardType" : "Debit Card",
		    "first6" : "424242",
		    "last4" : "4242"
		  },
		  "flow" : {
		    "nextAction" : "none"
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "ideal",
		  "status" : "chargeable",
		  "billing" : {
		    "address" : {
		      "country" : "NL"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "latvianbanks",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "LV"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "lithuanianbanks",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "LT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "maxima",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "LT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "multibanco",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "PT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "mybank",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "IT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "p24",
		  "status" : "chargeable",
		  "billing" : {
		    "address" : {
		      "country" : "PL"
		    },
		    "email" : "[email protected]"
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "paypost",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "LT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "paysafecard",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "AT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "paysafecash",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "AT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "paysera",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "EE"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "payu",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "CZ"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "perlas",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "LT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "skrill",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "US"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "three_d_secure",
		  "status" : "pending",
		  "billing" : {
		    "address" : {
		      "country" : "US"
		    }
		  },
		  "threeDSecure" : {
		    "amount" : 1000,
		    "currency" : "USD"
		  },
		  "source" : {
		    "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		    "created" : 1415810511,
		    "objectType" : "payment_method",
		    "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		    "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		    "type" : "google_pay",
		    "status" : "chargeable",
		    "billing" : {
		      "address" : {
		        "country" : "US"
		      }
		    },
		    "googlePay" : {
		      "cardBrand" : "Visa",
		      "cardType" : "Debit Card",
		      "first6" : "424242",
		      "last4" : "4242"
		    },
		    "flow" : {
		      "nextAction" : "none"
		    }
		  },
		  "flow" : {
		    "nextAction" : "three_d_secure"
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "trustly",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "AT"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "unionpay",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "US"
		    },
		    "email" : "[email protected]"
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "verkkopankki",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "FI"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

{
	"list" : [
		{
		  "id" : "pm_BokS87jDShjASDkjhdsak4kl",
		  "created" : 1415810511,
		  "objectType" : "payment_method",
		  "clientObjectId" : "client_pm_kjdS8DSj73DSkjhKJHDKSAna",
		  "customerId" : "cust_BokS87jDShjASDkjhdsak4kl",
		  "type" : "wechatpay",
		  "status" : "chargeable",
		  "billing" : {
		    "name" : "Werner Heisenberg",
		    "address" : {
		      "country" : "CN"
		    }
		  }
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}