Arrow leftGo to Shift4.com

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:

  • amount_too_high - The specified amount is greater than the maximum amount allowed.

  • amount_too_low - The specified amount is lower than the minimum amount allowed.

  • invalid_number - The card number is not a valid one.

  • invalid_number - Your request was in test mode, but used a non test card. For a list of valid test cards, visit our doc site.

  • invalid_expiry_month - The card's expiration month is invalid.

  • invalid_expiry_year - The card's expiration year is invalid.

  • invalid_cvc - Your card's security code is invalid.

  • incorrect_cvc - The card's security code failed verification.

  • invalid_account - Account details failed verification.

  • incorrect_zip - The card's zip code failed verification.

  • incorrect_address - The card's address failed verification.

  • expired_card - The card has expired.

  • insufficient_funds - The charge amount exceeds the available fund or the card's credit limit.

  • lost_or_stolen - The card is marked as lost or stolen.

  • suspected_fraud - The charge is suspected to be fraudulent.

  • card_declined - The card was declined for another reason.

  • brand_not_supported- The card brand is not supported.

  • currency_not_supported - Your account is not configured to process given currency. Please contact [email protected] for details.

  • processing_error - An error occurred while processing the card.

  • expired_token - The token has expired.

  • authentication_required - The charge requires authentication.

  • blocked - Transaction was blocked by rules engine.

  • call_issuer - The card was declined for an unknown reason. Contact the card issuer for more information.

  • limit_exceeded - You have exceeded bank's refund limit.

  • do_not_try_again - The card was declined and should not be retried.

  • payment_method_declined - The payment method was declined


message | string

A human-readable message that describes the reason for this error. Note that the content of this message is not intended to be parsed, and the format of this message can change at any moment.

issuerDeclineCode | string

Error code supplied by the card issuer. Only present when the request resulted in a declined charge, and that charge was declined by the card issuer.

chargeId | string

Identifier of the charge object associated with this error. Only present when the request resulted in a declined charge.

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

arn | string

Acquirer Reference Number

shipping | object

Shipping details. Can contain the following attributes:

  • name (string) - name of the recipient

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a two-letter ISO country code

  • phone (string) - phone of the recipient

billing | object

Billing details. Can contain the following attributes:

  • name (string) - name of billed person or company

  • email (string) - email of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a wo-letter ISO country code

  • phone (string) - phone of billed person or company

  • vat (string) - tax identification number

threeDSecureInfo | object

Additional data present if card used to create this charge was verified with 3D Secure. Can contain following attributes:

  • amount (integer) - amount in minor units that was used in 3D Secure

  • currency (string) - currency that was used in 3D Secure (represented as a three-letter ISO currency code)

  • enrolled (boolean) - information on whether the card used to create this charge supports 3D Secure

  • liabilityShift (string) - can have one of the following values:

    • null - 3D Secure was not started or is in 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


aniCheck | object

Contains field result that informs about the outcome of the ANI check. Possible values: full_match, partial_match, no_match, not_verified, not_supported.

merchantAccountId | string

Identifier of the merchant account that was used to create this charge.

metadata | metadata object

failureCode | string

Error code that describes why the charge has failed. Only present in failed charges. For the list of possible values, see the code attribute in the error object.

failureMessage | string

A human-readable message that describes why the charge has failed. Only present in failed charges.

failureIssuerDeclineCode | string

Error code supplied by the card issuer. Only present in failed charges.

EXAMPLE OBJECT

Create a new Charge

Creates a new charge object.

Capturing a charge object (either at creation or at the later stage) will result in the charge of provided credit or debit card.

If you are in test mode, the provided credit or debit card won't actually be charged, but everything else will work the same as in live mode.

Arguments


amount | integer, required

Charge amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency | string, required

Charge currency represented as a three-letter ISO currency code

type | string, optional

Possible values are: first_recurring, subsequent_recurring, merchant_initiated, customer_initiated.

description | string, optional

customerId | string, optional (either customerId or card is required)

Identifier of the customer that will be associated with this charge. This field is required if the charge is being created with the customer's existing card. If specified, the successful charge created with a new card will add that card to the customer's cards and be set as customer's default card.


card | card token, card details or card identifier, optional (either customerId, card or paymentMethod is required)

Can be one of the following:

  • card token (for example, obtained from Components)

  • card details (same as in the card create request)

  • card identifier (must be an existing card that is associated with the customer-specified in customerId field)

If neither card nor payment method is provided, the customer's defaults will be used.

paymentMethod | payment method details or identifier, optional (either customerId, card or paymentMethod is required)

It can be one of the following:

  • payment method details (same as in payment method create request)

  • payment method identifier (must be an existing payment method that is associated with customer specified in customerId field)

If neither card nor payment method is provided, then the customer's defaults will be used.

flow | details specific to the payment method charge. Specifies payment process details.

  • returnUrl (required for paymentMethod charge) - URL to which the user will be redirected after processing payment on an external site. For convenience query parameter clientObjectId will be added, which can be afterwards used to check the charge status with shift4.js.


captured | boolean, optional (default is true)

Whether this charge should be immediately captured. When set to false charge is only authorized (or pre-authorized) and needs to be captured later.

shipping | object, optional

Shipping details. Can contain the following attributes:

  • name (string) - name of the recipient

  • address (object) - address object, can contain following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as two-letter ISO country code

  • phone (string) - phone of the recipient, eg. +12345678901

billing | object, optional, cannot be used together with paymentMethod

Billing details. Can contain the following attributes:

  • name (string) - name of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a two-letter ISO country code

  • phone (string) - phone of billed person or company, eg. +12345678901

  • vat (string) - tax identification number

threeDSecure | object, optional

3D Secure options. It can contain the following attributes:

  • requireAttempt (boolean, default is false) - the charge will fail when the 3D Secure verification was not attempted

  • requireEnrolledCard (boolean, default is false) - the charge will fail if the card doesn't support 3D Secure (is not enrolled for 3D Secure verification)

  • requireSuccessfulLiabilityShiftForEnrolledCard (boolean, default is true) - the charge will fail when the card supports the 3D Secure verification, but that verification was not successful (i.e. customer cancelled the verification or provided invalid information in the 3D Secure popup)

  • external (object, optional) - used with an external 3DS service and can contain the following attributes:

    • version (string, required) - with one of following values: 2.1.0 and 2.2.0

    • eci (string, required) - Electronic Commerce Indicator e.g., 05

    • authenticationValue (string, optional) - other names: CAVV, AAV, UCAF

    • dsTransactionId (string, required for 3DS 2) - dsTransID received in ARes

    • acsTransactionId (string, required for 3DS 2) - acsTransID received in ARes

    • status (string, required) - can have one of the following values: Y, N, A, U, R, E


merchantAccountId | string, optional

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


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

EXAMPLE RESPONSE

Retrieve an existing Charge

Retrieves an existing charge object.

Arguments


CHARGE_ID | string, required

Identifier of the the charge object that should be retrieved.

Result

Successful request returns a charge object.

DEFINITION

GET https://api.shift4.com/charges/{CHARGE_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "USD",
	"description" : "Example charge",
	"card" : {
	  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	  "created" : 1415810511,
	  "objectType" : "card",
	  "first6" : "424242",
	  "last4" : "4242",
	  "fingerprint" : "e3d8suyIDgFg3pE7",
	  "expMonth" : "11",
	  "expYear" : "2028",
	  "cardholderName" : "John Doe",
	  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	  "brand" : "Visa",
	  "type" : "Credit Card",
	  "issuer" : "Card Issuer Name",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false,
}

Update an existing Charge

Update an existing charge object.

Any not provided parameter will be left unchanged.

Arguments



CHARGE_ID | string, required

Identifier of charge object that should be updated.

customerId | string, optional

Identifier of customer that will be associated with this charge. Updating this field is only possible for the charge that is not assigned to any customer. Assigning a successful charge to the customer will result in adding the card used to create that charge to the customer's cards. The card will be set as the customer's default card.

description | string, optional


shipping | object, optional

Shipping details. Can contain the following attributes:

  • name (string) - name of the recipient

  • address (object) - address object, can contain following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as two-letter ISO country code

  • phone (string) - phone of the recipient, eg. +12345678901

billing | object, optional, cannot be used together with paymentMethod

Billing details. Can contain the following attributes:

  • name (string) - name of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a two-letter ISO country code

  • phone (string) - phone of billed person or company, eg. +12345678901

  • vat (string) - tax identification number


fraudDetails | object, optional

Fraud details. It contains the attribute:

  • status (string) - can be one of the following: safe, suspicious, fraudulent, in_progress 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" : "2028",
	  "cardholderName" : "John Doe",
	  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	  "brand" : "Visa",
	  "type" : "Credit Card",
	  "issuer" : "Card Issuer Name",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false
}

Capture a Charge

Capture an existing charge that was created with the captured=false attribute. This is the second part of two-step payment flow.

Arguments

CHARGE_ID | string, required

Identifier of the charge object that should be captured.

Result

A successful request returns a charge object that was captured.

DEFINITION

POST https://api.shift4.com/charges/{CHARGE_ID}/capture

EXAMPLE REQUEST

 curl https://api.shift4.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q/capture \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X POST

EXAMPLE RESPONSE

{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "USD",
	"description" : "Example charge",
	"card" : {
	  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	  "created" : 1415810511,
	  "objectType" : "card",
	  "first6" : "424242",
	  "last4" : "4242",
	  "fingerprint" : "e3d8suyIDgFg3pE7",
	  "expMonth" : "11",
	  "expYear" : "2028",
	  "cardholderName" : "John Doe",
	  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	  "brand" : "Visa",
	  "type" : "Credit Card",
	  "issuer" : "Card Issuer Name",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false
}

List Charges

List charge objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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 (either customerId or card is required)



Result

A successful request returns a list of charge objects.

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

DEFINITION

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

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
			"created" : 1415810511,
			"objectType" : "charge",
			"amount" : 499,
			"currency" : "USD",
			"description" : "Example charge",
			"card" : {
			  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			  "created" : 1415810511,
			  "objectType" : "card",
			  "first6" : "424242",
			  "last4" : "4242",
			  "fingerprint" : "e3d8suyIDgFg3pE7",
			  "expMonth" : "11",
			  "expYear" : "2028",
			  "cardholderName" : "John Doe",
			  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			  "brand" : "Visa",
			  "type" : "Credit Card",
			  "issuer" : "Card Issuer Name",
			  "country" : "CH"
			},
			"captured" : true,
			"refunded" : false,
			"disputed" : false
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Dispute object

Attributes



objectType | string (value is always "dispute").


created | timestamp


updated | timestamp


amount | integer

Dispute amount in minor units of a given currency. For example, 10€ is represented as "1000", and 10¥ is represented as "10".

currency | string

Dispute currency represented as a three-letter ISO currency code.


status | string

It can have one of the following values:

  • RETRIEVAL_REQUEST_NEW

  • RETRIEVAL_REQUEST_REPRESENTED

  • CHARGEBACK_NEW

  • CHARGEBACK_REPRESENTED_SUCCESSFULLY

  • CHARGEBACK_REPRESENTED_UNSUCCESSFULLY


reason | string

It can have one of the following values:

  • FRAUDULENT

  • UNRECOGNIZED

  • DUPLICATE

  • SUBSCRIPTION_CANCELED

  • PRODUCT_NOT_RECEIVED

  • PRODUCT_UNACCEPTABLE

  • CREDIT_NOT_PROCESSED

  • GENERAL

acceptedAsLost | boolean

EXAMPLE OBJECT

{
	"objectType" : "dispute",
	"created" : 1415896911,
	"updated" : 1415896911,
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"amount" : 499,
	"currency" : "USD",
	"acceptedAsLost" : false
}

Refunds

Refund represents a refund of a charge.

Refund object

Attributes


id | string


created | timestamp


amount | integer

Refund amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".


currency | string

Refund currency represented as a three-letter ISO currency code.

objectType | string (value is always "refund")

charge | string

ID of the charge associated with this refund.

reason | string

Reason of charge refund. Possible values are: fraudulent

status | string

Possible values are: successful, failed


metadata | metadata object, optional

EXAMPLE OBJECT

{
	"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
	"created" : 1609325894,
	"amount" : 100,		
	"currency" : "USD",
	"objectType" : "refund",
	"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
	"reason" : "fraudulent",				
	"status" : "successful"
}

Refund a Charge

Refund an existing charge, which will result in funds being returned to the previously charged credit or debit card.

Partial refunds are only possible for captured charge. The partial refunds can be repeated for as long as the charge is not fully refunded.

Note that if there is an active subscription related to this charge, it won't be affected by this operation. If you want to cancel a subscription, you must make it in a separate request.


Arguments



chargeId | string, required

Identifier of the charge object that should be refunded.


amount | integer, optional (default is the current amount of charge)

Amount (in minor units) to refund. This must be less or equal to the current amount of charge that is being refunded.


reason | string

Reason of charge refund. Possible values are: fraudulent


metadata | metadata object, optional


Result

A successful request returns a refund object.

DEFINITION 

POST https://api.shift4.com/refunds

EXAMPLE REQUEST

curl https://api.shift4.com/refunds \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "chargeId=char_ZNmWK4pUECfFQTY0N4WMKeh3&amount=499"

EXAMPLE RESPONSE


{
	"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
	"created" : 1609325894,
	"amount" : 100,		
	"currency" : "USD",
	"objectType" : "refund",
	"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
	"reason" : "fraudulent",				
	"status" : "successful"
}

Retrieve an existing Refund


Arguments



REFUND_ID | string, required

Identifier of the refund object that should be retrieved.

Result

A successful request returns a refund object.

DEFINITION 

GET https://api.shift4.com/refunds/{REFUND_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/refunds/re_CNiqwdKHpX3o4SD4PWJxM5CF \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
	"created" : 1609325894,
	"amount" : 100,		
	"currency" : "USD",
	"objectType" : "refund",
	"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
	"reason" : "fraudulent",				
	"status" : "successful"
}

Update an existing Refund

Updates an existing refund object.


Arguments



metadata | metadata object, optional


Result

A successful request returns a refund object.

DEFINITION 

POST https://api.shift4.com/refunds/{REFUND_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/refunds/re_CNiqwdKHpX3o4SD4PWJxM5CF \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d '{"metadata": {"key": "value"}}'

EXAMPLE RESPONSE

{
  "id": "re_CNiqwdKHpX3o4SD4PWJxM5CF",
  "created": 1609325894,
  "amount": 100,
  "currency": "USD",
  "objectType": "refund",
  "charge": "char_ZNmWK4pUECfFQTY0N4WMKeh3",
  "reason": "fraudulent",
  "status": "successful",
  "metadata": {
    "key": "value"
  }
}

List Refunds

List refund objects.

Arguments



created | object, optional

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

  • gt - return objects created after given 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.


chargeId | string, required

Identifier of the charge object for which refunds should be listed.

Result

A successful request returns a list of refund objects.

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

DEFINITION

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

EXAMPLE REQUEST

curl "https://api.shift4.com/refunds?chargeId=char_ZNmWK4pUECfFQTY0N4WMKeh3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
  "list": [
    {
      "id": "re_CNiqwdKHpX3o4SD4PWJxM5CF",
      "created": 1609325894,
      "amount": 100,
      "currency": "USD",
      "objectType": "refund",
      "charge": "char_ZNmWK4pUECfFQTY0N4WMKeh3",
      "reason": "fraudulent",
      "status": "successful"
    },
    {
      "...": "..."
    },
    {
      "...": "..."
    }
  ],
  "hasMore": true
}

Customers



Customers allows to store cards for later use and to perform automatically recurring charges. Customers are also useful for tracking charges that are associated with the same entity.

Customer object

Attributes



id | string

created | timestamp


objectType | string (value is always "customer")

email | string

description | string


defaultCardId | string

Identifier of the customer's default card.


cards | list of card object

List of 10 most recent cards associated with this customer.


metadata | metadata object

EXAMPLE OBJECT

{
  "id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "created" : 1415810511,
  "objectType" : "customer",
  "email" : "[email protected]",
  "description" : null,
  "defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "cards" : [
    {
      "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
      "created" : 1415810511,
      "objectType" : "card",
      "first6" : "424242",
      "last4" : "4242",
      "fingerprint" : "e3d8suyIDgFg3pE7",
      "expMonth" : "11",
      "expYear" : "2028",
      "cardholderName" : "John Doe",
      "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
      "brand" : "Visa",
      "type" : "Credit Card",
      "issuer" : "Card Issuer Name",
      "country" : "CH"
    }
  ],
  "metadata" : { }
}

Create a Customer

Creates a new customer object.

Arguments



email | string, required

description | string, optional

card | charge identifier, card token or card details, optional

If provided, the customer will be created with this card and the card will be set as default. Can be one of the following:

  • card token (for example obtained from Components)

  • charge identifier - will save the card that was used to create a charge (only possible for successful charge not assigned to any other customer and will result in that charge being assigned to this customer)

  • card details (the same as in card create request)

metadata | metadata object, optional

Result

A successful request returns a customer object that represents the created customer.

DEFINITION

POST https://api.shift4.com/customers

EXAMPLE REQUEST

curl https://api.shift4.com/customers \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "[email protected]" \
	-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe"

EXAMPLE RESPONSE

{
  "id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "created" : 1415810511,
  "objectType" : "customer",
  "email" : "[email protected]",
  "defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "cards" : [
    {
      "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
      "created" : 1415810511,
      "objectType" : "card",
      "first6" : "424242",
      "last4" : "4242",
      "fingerprint" : "e3d8suyIDgFg3pE7",
      "expMonth" : "11",
      "expYear" : "2028",
      "cardholderName" : "John Doe",
      "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
      "brand" : "Visa",
      "type" : "Credit Card",
      "issuer" : "Card Issuer Name",
      "country" : "CH"
    }
  ]
}

Retrieve an existing Customer

Retrieves an existing customer object.

Arguments

CUSTOMER_ID | string, required

Identifier of the customer object that should be retrieved.

Result

A successful request returns a customer object.

DEFINITION

GET https://api.shift4.com/customers/{CUSTOMER_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
  "id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "created" : 1415810511,
  "objectType" : "customer",
  "email" : "[email protected]",
  "defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "cards" : [
    {
      "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
      "created" : 1415810511,
      "objectType" : "card",
      "first6" : "424242",
      "last4" : "4242",
      "fingerprint" : "e3d8suyIDgFg3pE7",
      "expMonth" : "11",
      "expYear" : "2028",
      "cardholderName" : "John Doe",
      "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
      "brand" : "Visa",
      "type" : "Credit Card",
      "issuer" : "Card Issuer Name",
      "country" : "CH"
    }
  ]
}

Update an existing Customer

Update an existing customer object.

Any not provided parameter will be left unchanged.

Arguments

CUSTOMER_ID | string, required

Identifier of the customer object that should be updated.

email | string, optional

description | string, optional


defaultCardId | string, optional

Identifier of the customer's card that will be set as the default one.


card | charge identifier, card token or card details, optional

If provided, the new card will be added to the customer's cards and the card will be set as default. Can be one of the following:

  • card token (for example obtained from Components)

  • charge identifier - will save the card that was used to create a charge (only possible for successful charge not assigned to any other customer, and will result in that charge being assigned to this customer)

  • card details (same as in card create request)

metadata | metadata object ,optional

Result

A successful request returns a customer object that was updated.

DEFINITION

POST https://api.shift4.com/customers/{CUSTOMER_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "[email protected]" \
	-d "description=New description"

EXAMPLE RESPONSE

{
  "id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "created" : 1415810511,
  "objectType" : "customer",
  "email" : "[email protected]",
  "description" : "New description",
  "defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "cards" : [
    {
      "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
      "created" : 1415810511,
      "objectType" : "card",
      "first6" : "424242",
      "last4" : "4242",
      "fingerprint" : "e3d8suyIDgFg3pE7",
      "expMonth" : "11",
      "expYear" : "2028",
      "cardholderName" : "John Doe",
      "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
      "brand" : "Visa",
      "type" : "Credit Card",
      "issuer" : "Card Issuer Name",
      "country" : "CH"
    }
  ]
}

Delete a Customer

Deletes an existing customer object.

Arguments

CUSTOMER_ID | string, required

Identifier of the customer object that should be deleted.

Result

A successful request returns identifier of the deleted customer object.

DEFINITION

DELETE https://api.shift4.com/customers/{CUSTOMER_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE

EXAMPLE RESPONSE

{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
}

List Customers

List customer objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.

endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.

email | string, optional

Returns only customers with a given email.

Result

A successful request returns a list of customer objects.

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

DEFINITION

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

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
	"list" : [
		{
		  "id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "created" : 1415810511,
		  "objectType" : "customer",
		  "email" : "[email protected]",
		  "defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		  "cards" : [
		    {
		      "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		      "created" : 1415810511,
		      "objectType" : "card",
		      "first6" : "424242",
		      "last4" : "4242",
		      "fingerprint" : "e3d8suyIDgFg3pE7",
		      "expMonth" : "11",
		      "expYear" : "2028",
		      "cardholderName" : "John Doe",
		      "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		      "brand" : "Visa",
		      "type" : "Credit Card",
		      "issuer" : "Card Issuer Name",
		      "country" : "CH"
		    }
		  ]
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

Cards


Card represents a credit or a debit card.

Cards are used to save credit or debit card data for later use. Cards can also be used to represent card data in other operations (for example to specify card data when creating a new charge).

Card object

Attributes

id | string

created | timestamp

objectType | string (value is always "card")


first6 | integer


last4 | integer

fingerprint | string

Unique identifier of the card number. Can be used to check if two different charges were done using the same card number.


expMonth | integer

expYear | integer

cardholderName | string

customerId | string

Identifier of the customer that is the owner of this card.

brand | string

Brand of card. Possible values are: Visa, American Express, MasterCard, Discover, JCB, Diners Club, Unknown

type | string

Type of card. Possible values are: Credit Card, Debit Card, Prepaid Card, Unknown

country | string

Country of card's Issuing Bank (represented as a two-letter ISO country code). This value is derived from the card's Bank Identification Number (BIN).


issuer | string

Name of card's Issuing Bank


addressLine1 | string

addressLine2 | string

addressCity | string

addressState | string

addressZip | string


addressCountry | string

Country represented as a three-letter ISO country code.

fraudCheckData | object

Additional data used for fraud protection. Can contain the following attributes:

  • ipAddress (string) - IP address of the user

  • ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)

  • email (string) - e-mail address of the user

  • phone (string) - phone number of the user

  • userAgent (string) - value of "User-Agent" HTTP header that was sent by the user

  • acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

  • browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token

merchantAccountId | string

Identifier of the merchant account that was used to create this card.

fastCredit | object

Additional data present if this card was checked for support of fast credits. This check can be performed by updating card with checkFastCredit = true. Contains the following attributes:

  • supported (boolean) - Indicates whether the card supports fast credit

  • updated (timestamp) - Indicated the last time fast credit status has been refreshed

EXAMPLE OBJECT

{
  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "created" : 1415810511,
  "objectType" : "card",
  "first6" : "424242",
  "last4" : "4242",
  "fingerprint" : "e3d8suyIDgFg3pE7",
  "expMonth" : "11",
  "expYear" : "2028",
  "cardholderName" : "John Doe",
  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "brand" : "Visa",
  "type" : "Credit Card",
  "issuer" : "Card Issuer Name",
  "country" : "CH",
  "fastCredit" : {
    "supported" : true,
    "updated" : 1415811511
  }
}

Create a new Card

Creates a new card object.

There are three ways to create a new card object:

  • use card token (for example obtained from Components)

  • use charge identifier - will save the card that was used to create a charge (only possible for successful charge not assigned to any other customer and will result in that charge being assigned to this customer)

  • specify all card details (as seen in the arguments list below)

Arguments



number | string, required

Card number without any separators.

expMonth | string, required

Card expiration month.


expYear | string, required

Card expiration year.


cvc | string, required

Card security code.


cardholderName | string, optional


addressLine1 | string, optional


addressLine2 | string, optional

addressCity | string, optional


addressState | string, optional

addressZip | string, optional

addressCountry | string, optional

Country represented as a three-letter ISO country code.

fraudCheckData | object

Additional data used for fraud protection. Can contain the following attributes:

  • ipAddress (string) - IP address of the user

  • ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)

  • email (string) - e-mail address of the user

  • phone (string) - phone number of the user, eg. +12345678901

  • userAgent (string) - value of "User-Agent" HTTP header that was sent by the user

  • acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

  • browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token

Result

A successful request returns a card object that represents the created card.

DEFINITION

POST https://api.shift4.com/customers/{CUSTOMER_ID}/cards

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "id=tok_NGsyDoJQXop5Pqqi6HizbJTe"

EXAMPLE RESPONSE

{
  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "created" : 1415810511,
  "objectType" : "card",
  "first6" : "424242",
  "last4" : "4242",
  "fingerprint" : "e3d8suyIDgFg3pE7",
  "expMonth" : "11",
  "expYear" : "2028",
  "cardholderName" : "John Doe",
  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "brand" : "Visa",
  "type" : "Credit Card",
  "issuer" : "Card Issuer Name",
  "country" : "CH"
}

Retrieve an existing Card

Retrieves an existing card object.

Arguments


CUSTOMER_ID | string, required

Identifier of the customer object that is the owner of the card object that should be retrieved.


CARD_ID | string, required

Identifier of the card object that should be retrieved.

Result

A successful request returns a card object.

DEFINITION

GET https://api.shift4.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "created" : 1415810511,
  "objectType" : "card",
  "first6" : "424242",
  "last4" : "4242",
  "fingerprint" : "e3d8suyIDgFg3pE7",
  "expMonth" : "11",
  "expYear" : "2028",
  "cardholderName" : "John Doe",
  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "brand" : "Visa",
  "type" : "Credit Card",
  "issuer" : "Card Issuer Name",
  "country" : "CH"
}

Update an existing Card

Arguments


CUSTOMER_ID | string, required

Identifier of the customer object that is the owner of the card object that should be updated.


CARD_ID | string, required

Identifier of the card object that should be updated.


expMonth | integer

expYear | integer

cardholderName | string, optional


addressCity | string

addressState | string

addressZip | string


addressCountry | string

Country represented as a three-letter ISO country code.


addressLine1 | string

addressLine2 | string

checkFastCredit | boolean, optional

Indicates whether a check for fast credit support should be made.


Result

A successful request returns a card object that was updated.

DEFINITION 

POST https://api.shift4.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "cardholderName=Jane Doe"
	-d "checkFastCredit=true"

EXAMPLE RESPONSE

{
  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
  "created" : 1415810511,
  "objectType" : "card",
  "first6" : "424242",
  "last4" : "4242",
  "fingerprint" : "e3d8suyIDgFg3pE7",
  "expMonth" : "11",
  "expYear" : "2027",
  "cardholderName" : "Jane Doe",
  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "brand" : "Visa",
  "type" : "Credit Card",
  "issuer" : "Card Issuer Name",
  "country" : "CH",
  "fastCredit" : {
    "supported" : true,
    "updated" : 1415811511
  }
}

Delete a Card

Deletes an existing card object.

If you delete the card that is the current default card, then the most recently added card will be used as the new default card. If you delete the last card then teh default card will be set to null.


Arguments


CUSTOMER_ID | string, required

Identifier of the customer object that is the owner of the card object that should be deleted.


CARD_ID | string, required

Identifier of the card object that should be deleted.


Result

A successful request returns the identifier of the deleted card object.

DEFINITION 

DELETE https://api.shift4.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE

EXAMPLE RESPONSE

{
	"id": "card_8P7OWXA5xiTS1ISnyZcum1KV",

}

List Cards

List card objects for a given customer.

Arguments


customerId | string, required

Identifier of the customer object whose cards should be listed.


created | object, optional

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

  • gt - return objects created after given 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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.


endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.


Result

A successful request returns a list of card objects.

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

DEFINITION

GET https://api.shift4.com/customers/{CUSTOMER_ID}/cards

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
	"list" : [
		{
		  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		  "created" : 1415810511,
		  "objectType" : "card",
		  "first6" : "424242",
		  "last4" : "4242",
		  "fingerprint" : "e3d8suyIDgFg3pE7",
		  "expMonth" : "11",
		  "expYear" : "2028",
		  "cardholderName" : "John Doe",
		  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "brand" : "Visa",
		  "type" : "Credit Card",
		  "issuer" : "Card Issuer Name",
		  "country" : "CH"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

Subscriptions


A subscription represents a recurring payment that will result in a charge being automatically created for a given customer. The frequency and amount of these automatic charges are defined by a plan.

Subscriptions are always billed to the customer's current default card.

Subscription object


Attributes

id | string

created | timestamp

objectType | string (value is always "subscription")


planId | string

Identifier of a plan assigned to this subscription.


customerId | string

Identifier of a customer who is the owner of this subscription.


quantity | integer

Multiplier that will be applied to change the amount defined in a plan. For example a plan with amount=100 used in the subscription with quantity=5 will result in changes with amount=500.


captureCharges | boolean

Whatever charges created by this subscription will be immediately captured (see captured attribute in charge request). If set to false, then you need to manually capture each charge created by this subscription.

status | string

Status of this subscription. Possible values are:

  • trialing - subscription was created from a plan with trial days and is still in the trial 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, eg. +12345678901


billing | object, optional

Billing details. Can contain the following attributes:

  • name (string) - name of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a two-letter ISO country code

  • phone (string) - phone of billed person or company, eg. +12345678901

  • vat (string) - tax identification number

merchantAccountId | string, optional

Identifier of the merchant account that will be used to create charges for this subscription.

metadata | metadata object


Result

A successful request returns a subscription object that represents created subscription.

DEFINITION

POST https://api.shift4.com/subscriptions

EXAMPLE REQUEST

curl https://api.shift4.com/subscriptions \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "planId=plan_bLu3vzO8yhAFhbxFEadm6HUV" \
	-d "customerId=cust_AoR0wvgntQWRUYMdZNLYMz5R"

EXAMPLE RESPONSE

{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "active",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"cancelAtPeriodEnd" : false
}

Retrieve an existing Subscription

Retrieves an existing subscription object.

Arguments


SUBSCRIPTION_ID | string, required

Identifier of the subscription object that should be retrieved.


Result

A successful request returns a subscription object.

DEFINITION

GET https://api.shift4.com/subscriptions/{SUBSCRIPTION_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "active",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"cancelAtPeriodEnd" : false
}

Update an existing Subscription

Update an existing subscription object.

Any not provided parameter will be left unchanged.

Arguments


SUBSCRIPTION_ID | string, required

Identifier of the subscription object that should be updated.

planId | string, optional

Identifier of a plan that will be assigned to this subscription.

card | charge identifier, card token or card details, optional

If provided, the new card will be added to the customer's cards and it will be set as default. Can be one of the following:

  • card token (for example, obtained from Components)

  • charge identifier - will save the card that was used to create a charge (only possible for successful charge that is not assigned to any other customer and will result in that charge being assigned to this customer)

  • card details (the same as in the card create request)

quantity | integer, optional

captureCharges | boolean, optional

Any charges created by this subscription will be captured immediately (see captured attribute in the charge request). If set to false then you need to manually capture each charge created by this subscription.

currentPeriodEnd | string, optional

Defines the end of the current cycle for this subscription and a billing date for the next one. Should be sent as a timestamp. Special value of now can be used to end the cycle and start a new one immediately. If subscription is currently in trialing status, it affects the trial period.

shipping | object, optional

Shipping details. Can contain the following attributes:

  • name (string) - name of the recipient

  • address (object) - address object, can contain following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as two-letter ISO country code

  • phone (string) - phone of the recipient, eg. +12345678901

billing | object, optional

Billing details. Can contain the following attributes:

  • name (string) - name of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a two-letter ISO country code

  • phone (string) - phone of billed person or company, eg. +12345678901

  • vat (string) - tax identification number


merchantAccountId | string, optional

Identifier of the merchant account that will be used to create charges for this subscription.


metadata | metadata object, optional


Result

A successful request returns a subscription object that was updated.

DEFINITION 

POST https://api.shift4.com/subscriptions/{SUBSCRIPTION_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "quantity=5"

EXAMPLE RESPONSE

{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 5,
	"status" : "active",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"cancelAtPeriodEnd" : false
}

Cancel a Subscription

Cancels an existing subscription.

Arguments


SUBSCRIPTION_ID | string, required

Identifier of the subscription object that should be canceled.

atPeriodEnd | boolean, optional (default is false)

Whether or not to delay cancellation of the subscription until the end of the current period. By default the subscription is canceled immediately.


Result

A successful request returns a subscription object that was canceled.

DEFINITION

DELETE https://api.shift4.com/subscriptions/{SUBSCRIPTION_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE


EXAMPLE REQUEST (with atPeriodEnd)

curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5?atPeriodEnd=true \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE

EXAMPLE RESPONSE

{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "canceled",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"canceledAt" : 1415982979,
	"endedAt" : 1415982979,
	"cancelAtPeriodEnd" : false
}

List Subscriptions

Lists subscription objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.

endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.


customerId | string, optional

Identifier of the customer object whose subscriptions should be listed.

planId | string, optional

Identifier of the plan object whose subscriptions should be listed.


Result

A successful request returns a list of subscription objects.

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

DEFINITION

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

EXAMPLE REQUEST

curl https://api.shift4.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
			"created" : 1415982733,
			"objectType" : "subscription",
			"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"quantity" : 1,
			"status" : "active",
			"start" : 1415982733,
			"currentPeriodStart" : 1415982733,
			"currentPeriodEnd" : 1416846733,
			"cancelAtPeriodEnd" : false
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Plans

Plan represents an automatically recurring charge.

Plans are used when a subscription is created for a customer to define how often and how much a given customer will be charged.

Plan object

Attributes

id | string

created | timestamp

objectType | string (value is always "plan")


amount | integer

Subscription charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".


currency | string

Subscription charge currency represented as three-letter ISO currency code.


interval | string

Frequency of subscription charges. Possible values are: hour, day, week, month, year


intervalCount | integer

Number of intervals between subscription charges. For example interval=day and intervalCount=10 will result in charge every 10 days.


billingCycles | integer

Number of charges after which subscription will be automatically canceled. Value of null means no limit on number of charges.


name | string

Display name of this plan


trialPeriodDays | integer

Number of days between creation of subscription and the first charge.


recursTo | plan identifier

When subscription is automatically canceled (due to reaching limit of billingCycles) it will move to plan defined by this attribute.


metadata | metadata object

EXAMPLE OBJECT

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "USD",
	"interval" : "day",
	"intervalCount" : 10,
	"billingCycles" : null,
	"name" : "Example plan",
	"trialPeriodDays" : null,
	"recursTo" : null,
	"metadata" : {}
}

Create a Plan

Creates a new plan object.

Arguments

amount | integer, required

Subscription charge amount in minor units of a given currency. For example, 10€ is represented as "1000", and 10¥ is represented as "10".

currency | string, required

Subscription charge currency represented as a three-letter ISO currency code.

interval | string, required

Frequency of the subscription charges. Possible values are: hour, day, week, month, year

name | string, required

Displays the name of this plan

intervalCount | integer, optional (default is 1)

Number of intervals between the subscription charges. For example, interval=day and intervalCount=10 will result in a charge every 10 days.

billingCycles | integer, optional

Number of charges after which the subscription will be automatically canceled. Value of null means no limit on the number of charges.

trialPeriodDays | integer, optional (default is 0)

Number of days between the creation of the subscription and the first charge.

recursTo | plan identifier, optional

When the subscription is automatically canceled (due to reaching limit of billingCycles) it will move to the plan defined by this attribute.

metadata | metadata object, optional

Result

A successful request returns a plan object that represents the created plan.

DEFINITION

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

EXAMPLE REQUEST

curl https://api.shift4.com/plans \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "amount=499" \
	-d "currency=USD" \
	-d "interval=day" \
	-d "intervalCount=10" \
	-d "name=Example plan"

EXAMPLE RESPONSE

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "USD",
	"interval" : "day",
	"intervalCount" : 10,
	"name" : "Example plan",
	"trialPeriodDays" : 0
}

Retrieve an existing Plan

Retrieves an existing plan object.

Arguments


PLAN_ID | string, required

Identifier of the plan object that should be retrieved.

Result

A successful request returns a plan object.

DEFINITION

GET https://api.shift4.com/plans/{PLAN_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "USD",
	"interval" : "day",
	"intervalCount" : 10,
	"name" : "Example plan",
	"trialPeriodDays" : 0
}

Update an existing Plan

Update an existing plan object.

Any not provided parameter will be left unchanged.

Changing amount or currency of a plan will only affect future rebills of all subscriptions that are using this plan.

Arguments

PLAN_ID | string, required

Identifier of the plan object that should be updated.

amount | integer, optional

Subscription charge amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".

currency | string, optional

Subscription charge currency represented as a three-letter ISO currency code.

name | string, optional

Displays the name of this plan

metadata | metadata object, optional

Result

A successful request returns a plan object that was updated.

DEFINITION

POST https://api.shift4.com/plans/{PLAN_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "name=New plan"

EXAMPLE RESPONSE

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "USD",
	"interval" : "day",
	"intervalCount" : 10,
	"name" : "New plan",
	"trialPeriodDays" : 0
}

Delete a Plan

Deletes an existing plan object.

Note that when you delete a plan, the existing subscriptions will continue to be charged until they are canceled.

Arguments


PLAN_ID | string, required

Identifier of the plan object that should be deleted.

Result

A successful request returns identifier of the deleted plan object.

DEFINITION

DELETE https://api.shift4.com/plans/{PLAN_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE

EXAMPLE RESPONSE

{
	"id": "plan_bLu3vzO8yhAFhbxFEadm6HUV",
}

List Plans

List plan objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.

endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.


Result

A successful request returns a list of plan objects.

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

DEFINITION

DELETE https://api.shift4.com/plans/{PLAN_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
			"created" : 1415973454,
			"objectType" : "plan",
			"amount" : 499,
			"currency" : "USD",
			"interval" : "day",
			"intervalCount" : 10,
			"name" : "Example plan",
			"trialPeriodDays" : 0
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true

Events


Events can be used to get notifications when something interesting has happened. For example, the creation of a new successful charge will result in CHARGE_SUCCEEDED event.

We provide API methods to retrieve a single event and to list events. It is also possible to get notifications about the new events by using Webhooks.

Event object

Attributes


id | string

created | timestamp

objectType | string (value is always "event")

type | string

Type of event. For more information see list of event types.

data | object

Object that is a subject of this event. For example, an event with type=CHARGE_SUCCEEDED will have a charge object as the value of this attribute.

log | string

Identifier of request log associated with this event.

EXAMPLE OBJECT

{
	"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
	"created" : 1416305114,
	"objectType" : "event",
	"type" : "CHARGE_SUCCEEDED",
	"data" : {
		"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
		"created" : 1415810511,
		"objectType" : "charge",
		"amount" : 499,
		"currency" : "USD",
		"description" : "Example charge",
		"card" : {
		  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		  "created" : 1415810511,
		  "objectType" : "card",
		  "first6" : "424242",
		  "last4" : "4242",
		  "fingerprint" : "e3d8suyIDgFg3pE7",
		  "expMonth" : "11",
		  "expYear" : "2028",
		  "cardholderName" : "John Doe",
		  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "brand" : "Visa",
		  "type" : "Credit Card",
		  "issuer" : "Card Issuer Name",
		  "country" : "CH"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : false
	},
	"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}

Retrieve an Event

Retrieves an existing event object.

Arguments


EVENT_ID | string, required

Identifier of the event object that should be retrieved.



Result

A successful request returns an event object.

DEFINITION 

GET https://api.shift4.com/events/{EVENT_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/events/event_EY7CzyQiffJykW8rC5wSRnAj \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
	"created" : 1416305114,
	"objectType" : "event",
	"type" : "CHARGE_SUCCEEDED",
	"data" : {
		"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
		"created" : 1415810511,
		"objectType" : "charge",
		"amount" : 499,
		"currency" : "USD",
		"description" : "Example charge",
		"card" : {
			  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			  "created" : 1415810511,
			  "objectType" : "card",
			  "first6" : "424242",
			  "last4" : "4242",
			  "fingerprint" : "e3d8suyIDgFg3pE7",
			  "expMonth" : "11",
			  "expYear" : "2028",
			  "cardholderName" : "John Doe",
			  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			  "brand" : "Visa",
			  "type" : "Credit Card",
			  "issuer" : "Card Issuer Name",
			  "country" : "CH"
			},
		"captured" : true,
		"refunded" : false,
		"disputed" : false
	},
	"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}

List Events

List event objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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.

Result

A successful request returns a list of event objects.

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

DEFINITION

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

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
			"created" : 1416305114,
			"objectType" : "event",
			"type" : "CHARGE_SUCCEEDED",
			"data" : {
				"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
				"created" : 1415810511,
				"objectType" : "charge",
				"amount" : 499,
				"currency" : "USD",
				"description" : "Example charge",
				"card" : {
				  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
				  "created" : 1415810511,
				  "objectType" : "card",
				  "first6" : "424242",
				  "last4" : "4242",
				  "fingerprint" : "e3d8suyIDgFg3pE7",
				  "expMonth" : "11",
				  "expYear" : "2028",
				  "cardholderName" : "John Doe",
				  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
				  "brand" : "Visa",
				  "type" : "Credit Card",
				  "issuer" : "Card Issuer Name",
				  "country" : "CH"
				},
				"captured" : true,
				"refunded" : false,
				"disputed" : false
			},
			"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Types of Events

CHARGE_SUCCEEDED | a charge object

Occurs when a new charge is successfully created.

CHARGE_PENDING | a charge object

Occurs when a new charge processing is pending.

CHARGE_FAILED | a charge object

Occurs when the creation of a new charge fails.

CHARGE_UPDATED | a charge object

Occurs when a charge object is updated.

CHARGE_CAPTURED | a charge object

Occurs when a charge is captured.

CHARGE_REFUNDED | a charge object

Occurs when a charge is refunded.


CHARGE_DISPUTE_CREATED | a charge object

Occurs when a customer disputes a charge (either the chargeback or the retrieval request).

CHARGE_DISPUTE_UPDATED | a charge object

Occurs when an existing dispute is updated.

CHARGE_DISPUTE_WON | a charge object

Occurs when a dispute is resolved as won.

CHARGE_DISPUTE_LOST | a charge object

Occurs when a dispute is resolved as lost.

CHARGE_DISPUTE_FUNDS_WITHDRAWN | a charge object

Occurs when funds are removed from your account as a result of a dispute (a chargeback).

CHARGE_DISPUTE_FUNDS_RESTORED | a charge object

Occurs when previously withdrawn funds are restored as a result of a winning dispute.

CUSTOMER_CREATED | a customer object

Occurs when new a customer is created.

CUSTOMER_UPDATED | a customer object

Occurs when a customer is updated.

CUSTOMER_DELETED | a customer object

Occurs when a customer is deleted.

CUSTOMER_CARD_CREATED | a card object

Occurs when a new card is created for a customer.

CUSTOMER_CARD_UPDATED | a card object

Occurs when a customer's card is updated.

CUSTOMER_CARD_DELETED | a card object

Occurs when a customer's card is deleted.

CUSTOMER_SUBSCRIPTION_CREATED | a subscription object

Occurs when a new subscription is created for a customer.

CUSTOMER_SUBSCRIPTION_UPDATED| a subscription object

Occurs when a customer's subscription is updated.

CUSTOMER_SUBSCRIPTION_DELETED| a subscription object

Occurs when a customer's subscription is cancelled.

PLAN_CREATED | a plan object

Occurs when a new plan is created.

PLAN_UPDATED | a plan object

Occurs when a plan is updated.

PLAN_DELETED | a plan object

Occurs when a plan is deleted.

CREDIT_SUCCEEDED | a credit object

Occurs when a new credit is successfully created.

CREDIT_FAILED | a credit object

Occurs when the creation of a new credit fails.

CREDIT_UPDATED | a credit object

Occurs when a credit object is updated.

FRAUD_WARNING_CREATED | a fraud warning object

Occurs when a fraud warning is created.

FRAUD_WARNING_UPDATED | a fraud warning object

Occurs when a fraud warning is updated.

PAYOUT_CREATED | a payout object

Occurs when a payout is created.

PAYOUT_UPDATED | a payout object

Occurs when a payout is updated.

PAYOUT_CREATED | a payout object

Occurs when a payout is created.

PAYMENT_METHOD_CREATED | a payment method object

Occurs when a new payment method is successfully created.


PAYMENT_METHOD_UPDATED | a payment method object

Occurs when a payment method object is updated.


PAYMENT_METHOD_DELETED | a payment method object

Occurs when a payment method object is deleted.


PAYMENT_LINK_CREATED | a payment link object

Occurs when a payment link object is created.


PAYMENT_LINK_UPDATED | a payment links object

Occurs when a payment method object is updated, deactivated or reactivated.

Tokens


Tokens are used to represent a card in a situation where you don't want to process or store card-sensitive data on your servers. Tokens can be easily created directly in a browser with the use of Components, but you can also create tokens in other environments (for example, in mobile applications).

Tokens can be created with the use of either "API Public Key" or "API Secret Key". You can safely embed your "API Public Key" in JavaScript or in downloadable applications (like iPhone or Android apps), so you can easily create tokens directly from these applications.

Note that tokens are meant to be used as a temporary representation of card data, and each token can be used only once. You should not store tokens for long periods of time - if you want to store a card for later use you should use the token to either create new customer or add new card to the existing customer.

Token object

Attributes


id | string


created | timestamp

objectType | string (value is always "token")


first6 | integer


last4 | integer


fingerprint | integer

Unique identifier of the card number. Can be used to check if two different charges were done using the same card number.


expMonth | integer


expYear | integer


brand | string

Brand of card. Possible values are: Visa , American Express , MasterCard , Discover , JCB , Diners Club , Unknown


type | string

Type of card. Possible values are: Credit Card, Debit Card, Prepaid Card, Unknown


cardholderName | string


addressLine1 | string


addressLine2 | string


addressCity | string


addressState | string


addressZip | string


addressCountry | string

Country represented as a three-letter ISO country code.


used | boolean


card | card object

Card that was created from this token.

fraudCheckData | object

Additional data used for fraud protection. Can contain the following attributes:

  • ipAddress (string) - IP address of the user

  • ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)

  • email (string) - e-mail address of the user

  • phone (string) - phone number of the user

  • userAgent (string) - value of "User-Agent" HTTP header that was sent by the user

  • acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

  • browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token

threeDSecureInfo | object

Additional data present if card (represented by this token) was verified with 3D Secure. Can contain following attributes:

  • amount (integer) - amount in minor units that was used in 3D Secure

  • currency (string) - currency that was used in 3D Secure (represented as a three-letter ISO currency code)

  • enrolled (boolean) - information on whether the card used to create this charge supports 3D Secure

  • liabilityShift (string) - can have one of the following values:
    null - 3D Secure was not started or is in 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" : "2028",
  "cardholderName" : "John Doe",
  "brand" : "Visa",
  "type" : "Credit Card",
  "country" : "CH",
  "used" : true,
  "card" : {
    "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
    "created" : 1415810511,
    "objectType" : "card",
    "first6" : "424242",
    "last4" : "4242",
    "fingerprint" : "e3d8suyIDgFg3pE7",
    "expMonth" : "11",
    "expYear" : "2028",
    "cardholderName" : "John Doe",
    "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
    "brand" : "Visa",
    "type" : "Credit Card",
    "issuer" : "Card Issuer Name",
    "country" : "CH"
  }
}

Create a new Token

Creates a new token object.

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

Attributes


number | string, required

Card number without any separators.


expMonth | string, required

Card expiration month.


expYear | string, required

Card expiration year.


cvc | string, required

Card security code.


cardholderName | string, optional


addressLine1 | string, optional


addressLine2 | string, optional


addressCity | string, optional


addressState | string, optional


addressZip | string, optional


addressCountry | string, optional

Country represented as a three-letter ISO country code.

fraudCheckData | object

Additional data used for fraud protection. Can contain the following attributes:

  • ipAddress (string) - IP address of the user

  • ipCountry (string) - country derived from user's IP address (represented as two-letter ISO country code)

  • email (string) - e-mail address of the user

  • phone (string) - phone number of the user, eg. +12345678901

  • userAgent (string) - value of "User-Agent" HTTP header that was sent by the user

  • acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user
    This attribute is only supported for requests made with "API Secret Key".

For requests made with "API Public Key" value of this attribute is ignored and data is automatically collected from request.


Result

Successful request returns a token object that represents given card details.

DEFINITION

POST https://api.shift4.com/tokens

EXAMPLE REQUEST

curl https://api.shift4.com/tokens \
	-u pu_test_WVMFC9GFuvm54b0uorifKkCh: \
	-d "number=4242424242424242" \
	-d "expMonth=11" \
	-d "expYear=2028" \
	-d "cvc=123" \
	-d "cardholderName=John Doe"

EXAMPLE RESPONSE

{
  "id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
  "created" : 1415810511,
  "objectType" : "token",
  "first6" : "42424242",
  "last4" : "4242",
  "fingerprint" : "e3d8suyIDgFg3pE7",
  "expMonth" : "11",
  "expYear" : "2027",
  "cardholderName" : "John Doe",
  "brand" : "Visa",
  "type" : "Credit Card",
  "country" : "CH",
  "used" : false
}

Retrieve an existing Token

Retrieves an existing token object.

Arguments


TOKEN_ID | string, required

Identifier of the token object that should be retrieved.


Result

A successful request returns a token object.

DEFINITION

GET https://api.shift4.com/tokens/{TOKEN_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/tokens/tok_NGsyDoJQXop5Pqqi6HizbJTe \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
  "id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
  "created" : 1415810511,
  "objectType" : "token",
  "first6" : "42424242",
  "last4" : "4242",
  "fingerprint" : "e3d8suyIDgFg3pE7",
  "expMonth" : "11",
  "expYear" : "2027",
  "cardholderName" : "John Doe",
  "brand" : "Visa",
  "type" : "Credit Card",
  "country" : "CH",
  "used" : false
}

Initialize 3D Secure Process

Initialize a new 3D Secure authentication process.

Generally (apart from a few specialized use cases) it is not recommended to initialize 3D Secure from the API. You should use our Components or checkout integration that already supports 3D Secure authentication.

To complete the 3D Secure process initiated using this API call, you must:

  1. Ensure that the card supports 3D Secure by checking that enrolled filed in response is equal to true

  2. Redirect the user to redirectUrl or display that URL in an <iframe> tag.

  3. Wait for the user to return to returnUrl

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

If neither card nor payment method is provided, the customer's defaults will be used.


Result

A successful request returns an object with the following attributes:

enrolled | boolean

Whether the card used to start this 3D Secure process supports 3D Secure.

version | string

Version of 3D Secure which will be used for this 3D Secure process.

redirectUrl | string

URL that must be used to complete the 3D Secure process by the user. User must be either redirected to this URL or this URL must be displayed to the user in an <iframe> tag.

token | token object

Token that is being used for this 3D Secure process. This token must be used to create charge after this 3D Secure process is completed.



DEFINITION

POST https://api.shift4.com/3d-secure

EXAMPLE REQUEST

curl https://api.shift4.com/3d-secure \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "amount=499" \
	-d "currency=USD" \
	-d "card[number]=4012001800000016" \
	-d "card[expMonth]=11" \
	-d "card[expYear]=2028" \
	-d "card[cvc]=123" \
	-d "returnUrl=https://example.com/"

EXAMPLE RESPONSE

{
	"enrolled": true,
	"version": "2.2.0",
	"redirectUrl": "https://api.shift4.com/3d-secure/start/35WSIRL2Qm1JKsDXMohFVhGVj5AFptAhuN7Sa0oQ",
	"token": {
		"id": "tok_RBZVaNlPj70nNIQ2cIB2lYMI",
		"created": 1634561057,
		"objectType": "token",
		"first6": "401200",
		"last4": "0016",
		"fingerprint": "8bTF2cbb2ccGr7ws",
		"expMonth": "11",
		"expYear": "2028",
		"brand": "Visa",
		"type": "Credit Card",
		"country": "CH",
		"used": false,
		"threeDSecureInfo": {
			"amount": 499,
			"currency": "USD",
			"enrolled": true,
			"liabilityShift": "failed",
			"version": "2.2.0",
			"authenticationFlow": null
		}
	}
}

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.

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.

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" : "202",
	  "cardholderName" : "John Doe",
	  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	  "brand" : "Visa",
	  "type" : "Credit Card",
	  "issuer" : "Card Issuer Name",
	  "country" : "CH",
	  "fastCredit" : {
	    "supported" : true,
	    "updated" : 1415811511
	  }
	},
	"customerId" : null,
	"fast" : true,
	"metadata" : {}
}

Create a new Credit

Creates a new credit object.

If you are in test mode, then provided card won't receive any funds, although everything else will work the same as in live mode.

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

Retrieve an existing Credit

Retrieves an existing credit object.

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

Update an existing Credit

Update an existing credit object.

Any not provided parameter will be left unchanged.

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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.

endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.

customerId | string, optional

Returns only credits associated with the given customer.


Result

A successful request returns a list of credit objects.

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

DEFINITION

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

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
			"created" : 1415810511,
			"objectType" : "credit",
			"amount" : 499,
			"currency" : "USD",
			"description" : "Example credit",
			"card" : {
			  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			  "created" : 1415810511,
			  "objectType" : "card",
			  "first6" : "424242",
			  "last4" : "4242",
			  "fingerprint" : "e3d8suyIDgFg3pE7",
			  "expMonth" : "11",
			  "expYear" : "2028",
			  "cardholderName" : "John Doe",
			  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			  "brand" : "Visa",
			  "type" : "Credit Card",
			  "issuer" : "Card Issuer Name",
			  "country" : "CH"
			}
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Disputes



Dispute is created when a customer questions your charge with their bank or the credit card company. When this happens, you have an opportunity to respond by providing evidence that the charge is legitimate.

Dispute object

Attributes


id | string

created | timestamp

objectType | string (value is always "dispute")


updated | timestamp

amount | integer

Dispute amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".

currency | string

Dispute currency represented as a three-letter ISO currency code.

status | string

Current status of this dispute. Possible values are:

  • RETRIEVAL_REQUEST_NEW - retrieval request, response 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 OBJECT

{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "USD",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "USD",
		"card" : {
		  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		  "created" : 1415810511,
		  "objectType" : "card",
		  "first6" : "424242",
		  "last4" : "4242",
		  "fingerprint" : "e3d8suyIDgFg3pE7",
		  "expMonth" : "11",
		  "expYear" : "2028",
		  "cardholderName" : "John Doe",
		  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "brand" : "Visa",
		  "type" : "Credit Card",
		  "issuer" : "Card Issuer Name",
		  "country" : "CH"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}

Dispute Evidence object

Attributes


productDescription | string

A description of a product or service purchased by the customer including any details provided to the customer at the time of purchase.

customerName | string

The name of the customer.

customerEmail | string

Customer's email address provided during the purchasing process.

customerPurchaseIp | string

The IP address used by the customer while purchasing.

customerSignature | id of file upload

A scanned image or a photo of a document showing the customer's signature.

billingAddress | string

The billing address provided by the customer in the purchasing process.

receipt | id of file upload

Receipts and messages sent to the customer with the charge notification.

customerCommunication | id of file upload

Any communication with a customer that can help you win the dispute. These could be emails with proof of receiving the product or confirmation that the service was provided to the customer on the specified date.

serviceDate | string

The date on which a customer received the purchased service, displayed in a human-readable format.

serviceDocumentation | id of file upload

The documentation proving that the service was provided to the customer. It could be a copy of a signed contract, etc.

duplicateChargeId | string

The ID of the duplicated charge.

duplicateChargeDocumentation | id of file upload

Any documents with proof that there were two or more separated transactions. Include shipping details, receipt, packing list, etc.

duplicateChargeExplanation | string

Any information indicating that transactions were separated to prove that the prior charge wasn't duplicated.

refundPolicy | id of file upload

Your refund policy, as shown to the customer.

refundPolicyDisclosure | string

An explanation showing how and when the customer agreed to your refund policy.

refundRefusalExplanation | string

An explanation of why the customer is not entitled to a refund.

cancellationPolicy | id of file upload

Your subscription cancellation policy, as shown to the customer.

cancellationPolicyDisclosure | string

An explanation of how and when the customer agreed to your cancellation policy.

cancellationRefusalExplanation | string

An explanation showing that the customer continued using the product after the date they claimed to have stopped using it.

accessActivityLogs | id of file upload

Any evidence of the customer's activity after the date they claim to have cancelled the subscription, such as server or activity logs, IP addresses, etc.

shippingAddress | string

The shipping address to which a physical product was delivered. To maximize your chances of winning the dispute, the address should match a verified billing address.

shippingDate | string

The date on which a physical product began its route to the shipping address, displayed in a human-readable format and prior to the date of the dispute.

shippingCarrier | string

The name of the delivery service that shipped a physical product, eg. UPS, FedEx. If there are multiple carriers for the purchase, separate them with commas.

shippingTrackingNumber | string

The number given by the delivery service for a physical product. If there are multiple tracking numbers for one purchase, separate them with commas.

shippingDocumentation | id of file upload

Documentation with proof that cardholder received a product at the address provided in the purchasing process. This could be a document with the full shipping address, such as the shipment receipt, etc.

uncategorizedText | string

An explanation with further evidence that doesn't fit into any of the fields provided above.

uncategorizedFile | id of file upload

Any files or documents with further evidence that doesn't fit into any of the fields provided above.

EXAMPLE OBJECT

{
	"productDescription" : null,
	"customerName" : null,
	"customerEmail" : null,
	"customerPurchaseIp" : null,
	"customerSignature" : null,
	"billingAddress" : null,
	"receipt" : null,
	"customerCommunication" : null,
	"serviceDate" : null,
	"serviceDocumentation" : null,
	"duplicateChargeId" : null,
	"duplicateChargeDocumentation" : null,
	"duplicateChargeExplanation" : null,
	"refundPolicy" : null,
	"refundPolicyDisclosure" : null,
	"refundRefusalExplanation" : null,
	"cancellationPolicy" : null,
	"cancellationPolicyDisclosure" : null,
	"cancellationRefusalExplanation" : null,
	"accessActivityLogs" : null,
	"shippingAddress" : null,
	"shippingDate" : null,
	"shippingCarrier" : null,
	"shippingTrackingNumber" : null,
	"shippingDocumentation" : null,
	"uncategorizedText" : null,
	"uncategorizedFile" : null
}

Retrieve an existing Dispute

Retrieves an existing dispute object.

Arguments

DISPUTE_ID | string, required

Identifier of the dispute object that should be retrieved.

Result

A successful request returns a dispute object.

DEFINITION

GET https://api.shift4.com/disputes/{DISPUTE_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "USD",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "USD",
		"card" : {
		  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		  "created" : 1415810511,
		  "objectType" : "card",
		  "first6" : "424242",
		  "last4" : "4242",
		  "fingerprint" : "e3d8suyIDgFg3pE7",
		  "expMonth" : "11",
		  "expYear" : "2028",
		  "cardholderName" : "John Doe",
		  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "brand" : "Visa",
		  "type" : "Credit Card",
		  "issuer" : "Card Issuer Name",
		  "country" : "CH"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}

Update an existing Dispute

Updates an existing dispute object.

Any not provided parameter will be left unchanged.

Arguments


DISPUTE_ID | string, required

Identifier of the dispute object that should be updated.

submit | boolean, optional (default is true)

If true evidence would be submitted for review.

evidence | dispute evidence object, optional

Updating any attribute in evidence will submit all fields for review, unless submit=false is specified. Can have following attributes:

  • productDescription (string, optional)

  • customerName (string, optional)

  • customerEmail (string, optional)

  • customerPurchaseIp (string, optional)

  • customerSignature (string, optional) - id of file upload

  • billingAddress (string, optional)

  • receipt (string, optional) - id of file upload

  • customerCommunication (string, optional) - id of file upload

  • serviceDate (string, optional)

  • serviceDocumentation (string, optional) - id of file upload

  • duplicateChargeId (string, optional) - id of charge

  • duplicateChargeDocumentation (string, optional) - id of file upload

  • duplicateChargeExplanation (string, optional)

  • refundPolicy (string, optional) - id of file upload

  • refundPolicyDisclosure (string, optional)

  • refundRefusalExplanation (string, optional)

  • cancellationPolicy (string, optional) - id of file upload

  • cancellationPolicyDisclosure (string, optional)

  • cancellationRefusalExplanation (string, optional)

  • accessActivityLogs (string, optional) - id of file upload

  • shippingAddress (string, optional)

  • shippingDate (string, optional)

  • shippingCarrier (string, optional)

  • shippingTrackingNumber (string, optional)

  • shippingDocumentation (string, optional) - id of file upload

  • uncategorizedText (string, optional)

  • uncategorizedFile (string, optional) - id of file upload

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" : "2028",
		  "cardholderName" : "John Doe",
		  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "brand" : "Visa",
		  "type" : "Credit Card",
		  "issuer" : "Card Issuer Name",
		  "country" : "CH"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}

Close an existing Dispute

Closing the dispute indicates that you do not want to submit any further evidence and acknowledge it as lost.

Arguments

DISPUTE_ID | string, required

Identifier of the dispute object that should be closed.

Result

A successful request returns identifier of the closed dispute object.

DEFINITION

POST https://api.shift4.com/disputes/{DISPUTE_ID}/close

EXAMPLE REQUEST

curl https://api.shift4.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj/close \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X POST

EXAMPLE RESPONSE

{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "USD",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "USD",
		"card" : {
		  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		  "created" : 1415810511,
		  "objectType" : "card",
		  "first6" : "424242",
		  "last4" : "4242",
		  "fingerprint" : "e3d8suyIDgFg3pE7",
		  "expMonth" : "11",
		  "expYear" : "2028",
		  "cardholderName" : "John Doe",
		  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
		  "brand" : "Visa",
		  "type" : "Credit Card",
		  "issuer" : "Card Issuer Name",
		  "country" : "CH"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}

List Disputes

Lists dispute objects.

Arguments

created | object, optional

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

  • gt - return objects created after given 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.

Result

A successful request returns list of a dispute object.

DEFINITION

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

EXAMPLE REQUEST

curl https://api.shift4.com/disputes \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"list": [{
		"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
		"created" : 1489571590,
		"objectType" : "dispute",
		"updated" : 1489571590,
		"amount" : 1000,
		"currency" : "USD",
		"status" : "CHARGEBACK_NEW",
		"reason" : "GENERAL",
		"acceptedAsLost" : false,
		"charge" : {
			"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
			"created" : 1489571590,
			"objectType" : "charge",
			"amount" : 0,
			"currency" : "USD",
			"card" : {
			  "id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			  "created" : 1415810511,
			  "objectType" : "card",
			  "first6" : "424242",
			  "last4" : "4242",
			  "fingerprint" : "e3d8suyIDgFg3pE7",
			  "expMonth" : "11",
			  "expYear" : "2028",
			  "cardholderName" : "John Doe",
			  "customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			  "brand" : "Visa",
			  "type" : "Credit Card",
			  "issuer" : "Card Issuer Name",
			  "country" : "CH"
			},
			"captured" : true,
			"refunded" : false,
			"disputed" : true
		},
		"evidence" : {
			"productDescription" : "Exclusive black shoes",
			"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
		},
		"evidenceDetails" : {
			"hasEvidence" : true,
			"submissionCount" : 1
		}
	}]
}

File Uploads


File Upload objects are created by uploading a binary file (like an image or PDF document) to Shift4. Such an uploaded file can then be used in other API requests by providing its identifier.

Note that for the file upload API a different API endpoint must be used: https://uploads.api.shift4.com.

File Upload object

Attributes


id | string

created | timestamp

objectType | string (value is always "file_upload")

purpose | string

Purpose of this file object. Possible values are: dispute_evidence.

size | integer

Size of uploaded file in bytes.


type | string

Type of this file object. Possible values are: pdf, jpg, png.

url | string

Read-only URL from which this file can be downloaded.

EXAMPLE RESPONSE

{
	"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
	"created" : 1415810511,
	"objectType" : "file_upload",
	"purpose" : "dispute_evidence",
	"size" : 28461,
	"type" : "jpg"
}

Create a File Upload

Creates a new file upload object.

Arguments

file | multipart file, required

File size should not exceed 8MB (8388608 bytes).


purpose | string, required

Purpose of this file object. Possible values are: dispute_evidence


Result

A successful request returns a file upload object that represents the uploaded file.

DEFINITION

POST https://uploads.api.shift4.com/files

EXAMPLE REQUEST

curl https://uploads.api.shift4.com/files \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
    -F "purpose=dispute_evidence" \
    -F file="@example-file.jpg"

EXAMPLE RESPONSE

{
	"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
	"created" : 1415810511,
	"objectType" : "file_upload",
	"purpose" : "dispute_evidence",
	"size" : 28461,
	"type" : "jpg"
}

Retrieve an existing File Upload

Retrieves an existing file upload object.

Arguments

FILE_UPLOAD_ID | string, required

Identifier of the file upload object that should be retrieved.



Result

A successful request returns a file upload object.

DEFINITION

GET https://uploads.api.shift4.com/files/{FILE_UPLOAD_ID}

EXAMPLE REQUEST

curl https://uploads.api.shift4.com/files/file_2nayTQXBBjaVEPVtCwGCbqOj
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
	"created" : 1415810511,
	"objectType" : "file_upload",
	"purpose" : "dispute_evidence",
	"size" : 28461,
	"type" : "jpg"
}

List File Uploads

Lists file upload objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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.

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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.

endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.

chargeId | string, optional

Identifier of the charge object for which fraud warnings should be listed.

actionable | boolean, optional

Can be used to list only actionable fraud warnings (see actionable in fraud warning object).


Result

A successful request returns a list of fraud-warning objects.

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

DEFINITION

GET https://api.shift4.com/fraud-warnings

EXAMPLE REQUEST

curl "https://api.shift4.com/fraud-warnings" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
			"created" : 1609325894,
			"objectType" : "fraud_warning",
			"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
			"actionable" : true
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Payouts



Payout represents details of funds received from the acquirer. They are made on varying schedules, depending on your acquirer.

Payout object


Attributes


id | string

created | timestamp

objectType | string (value is always "payout")

amount | integer

Payout transfer amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".

periodStart | timestamp

Timestamp of the payout period start.

periodEnd | timestamp

Timestamp of the payout period end.

currency | string

Payout transfer currency represented as a three-letter ISO currency code.

merchantAccountId | string, optional

Identifier of the merchant account that was used to create this payout.

EXAMPLE OBJECT

{
	"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1413561422,
	"objectType" : "payout",
	"periodEnd" : 1413325441,
	"periodStart" : 1413012367,
	"amount" : 499,
	"currency" : "USD"
}

Retrieve an existing Payout


Retrieves an existing payout object.

Arguments

PAYOUT_ID | string, required

Identifier of the payout object that should be retrieved.

Result

A successful request returns a payout object.

DEFINITION

GET https://api.shift4.com/payouts/{PAYOUT_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/payouts/po_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1413561422,
	"objectType" : "payout",
	"periodEnd" : 1413325441,
	"periodStart" : 1413012367,
	"amount" : 499,
	"currency" : "USD"
}

List Payouts

Lists payout objects.

Arguments


created | object, optional

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

  • gt - return objects created after given 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.


Result

A successful request returns a list of payout objects.

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

DEFINITION

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

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
	"list" : [
		{
			"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
			"created" : 1413561422,
			"objectType" : "payout",
			"periodEnd" : 1413325441,
			"periodStart" : 1413012367,
			"amount" : 499,
			"currency" : "USD"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Payout transaction object

Attributes

id | string

created | timestamp

objectType | string (value is always "payout_transaction")

type | string

Type of this transaction. Possible values are:

  • charge

  • refund

  • credit

  • chargeback - disputed amount; exact definition may vary depending on the processor

  • chargeback_represented - disputed amount; exact definition may vary depending on the processor

  • reserve_withhold - amount witheld to a rolling reserve

  • reserve_release - amount released to a rolling reserve

  • acquirer_fee - acquirer’s commission

  • adjustment - fees not related to a rolling reserve, disputes or acquirer related fees, eg. custom contractual fees or card scheme related fees

amount | integer

Payout transaction amount in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".

fee | integer

Payout transaction related fee sum in minor units of a given currency. For example, 10€ is represented as "1000" and 10¥ is represented as "10".

currency | string

Payout transaction currency represented as a three-letter ISO currency code.

source (optional) | string

Related object id.

description (optional) | string

Additional info from the acquirer about the transaction.

exchangeRate (optional) | double

Exchange rate used when converting from transaction currency to payout currency.

EXAMPLE OBJECT

{
    "id" : "pot_Y8x0X5d5zoRj6uI26vibFwkz",
    "created" : 1604620800,
    "objectType" : "payout_transaction",
    "type" : "charge",
    "amount" : 413,
    "currency" : "USD",
    "fee" : 39,
    "source" : "char_1jmzPboimq0IDwz8zLXdX9qw",
    "payout" : "po_gb48tN1UdWznKQHexcAAlbkK"
}

List Payout transactions

List payout transaction objects.

Arguments

created | object, optional

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

  • gt - return objects created after given 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.

payout | string, optional if source argument present

Only transactions included in the payout will be returned

source | string, optional if payout argument present

Only transactions related to the source will be returned


Result

A successful request returns a list of payout transaction objects.

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

DEFINITION

GET https://api.shift4.com/payout-transactions

EXAMPLE REQUEST

curl "https://api.shift4.com/payout-transactions?payout=po_gb48tN1UdWznKQHexcAAlbkK" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"list" : [
		{
    "id" : "pot_Y8x0X5d5zoRj6uI26vibFwkz",
    "created" : 1604620800,
    "objectType" : "payout_transaction",
    "type" : "charge",
    "amount" : 413,
    "currency" : "USD",
    "fee" : 39,
    "source" : "char_1jmzPboimq0IDwz8zLXdX9qw",
    "payout" : "po_gb48tN1UdWznKQHexcAAlbkK"
},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}

Create a Test Payout

Creates test Payout based on test mode charges, refunds, chargebacks and credits.

Result

A successful request returns payout object.

DEFINITION

POST https://api.shift4.com/payouts

EXAMPLE REQUEST

curl -X POST "https://api.shift4.com/payouts" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
	"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1413561422,
	"objectType" : "payout",
	"periodEnd" : 1413325441,
	"periodStart" : 1413012367,
	"amount" : 499,
	"currency" : "USD"
}

Payment Method


Payment Method represents an alternative payment method different from the card payments.

Payment Methods object can be used to define details of the payment method that will be used during payments.

Show details for:

Payment Method object

                    

Attributes

id | string

created | timestamp

objectType | string (value is always "payment_method")

clientObjectId | string

Public identifier of the Payment Method that allows to securely access the object from client frontend code without exposing any sensitive data


customerId | string

Identifier of the customer that is the owner of this payment method.

type | string

The type of the payment method. For the selected payment method type it will be alipay

status | string

Status of payment method.

Possible values are:

  • chargeable - Payment Method is ready to be used to create a charge.

  • pending - Payment Method setup process is in progress.

  • failed - setup process of the Payment Method failed.

  • used - payment method was already charged and cannot be reused.

billing | object

Billing details. Can contain the following attributes:

  • name (string) - name of billed person or company

  • email (string) - email of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a wo-letter ISO country code

  • phone (string) - phone of billed person or company

  • vat (string) - tax identification number

fraudCheckData | object

Additional data used for fraud protection. Can contain the following attributes:

  • ipAddress (string) - IP address of the user

  • ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)

  • email (string) - e-mail address of the user

  • phone (string) - phone number of the user

  • userAgent (string) - value of "User-Agent" HTTP header that was sent by the user

  • acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

  • browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token

merchantAccountId | string

Identifier of the merchant account that was used to create this charge.

metadata | metadata object, optional

EXAMPLE OBJECT

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

Create a new Payment Method

Arguments

type | string, required

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

customerId | string, optional

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

merchantAccountId | string, optional

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

billing | object

Billing details. Can contain the following attributes:

  • name (string, required) - name of billed person or company

  • email (string) - email of billed person or company

  • address (object) - address object, can contain the following attributes:

    • line1 (string) - address first line

    • line2 (string) - address second line

    • zip (string) - ZIP (postal) code

    • city (string) - city or town

    • state (string) - state or province

    • country (string) - country represented as a two-letter ISO country code

  • vat (string) - tax identification number

fraudCheckData | object, optional

Additional data used for fraud protection. Can contain the following attributes:

  • ipAddress - IP address of the user

  • ipCountry (string) - country derived from the user's IP address (represented as two-letter ISO country code)

  • email (string) - e-mail address of the user

  • phone (string) - phone number of the user, eg. +12345678901

  • userAgent (string) - value of "User-Agent" HTTP header that was sent by the user

  • acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

  • browserFingerprint (string) - hashed device identifier, available if Shift4.js was used to create Token

metadata | metadata object, optional

Result

A successful request returns a payment method object that represents the created payment method.

DEFINITION 

POST https://api.shift4.com/payment-methods

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

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

Retrieve an existing Payment Method

Retrieves an existing payment method object.

  

          

Arguments

PAYMENT_METHOD_ID | string, required

Identifier of the payment method object that should be retrieved.

Result

A successful request returns a payment method object.

DEFINITION 

GET https://api.shift4.com/payment-methods/{PAYMENT_METHOD_ID}

EXAMPLE REQUEST


curl https://api.shift4.com/payment-methods/pm_8HeqP7ZurLKhBPknC5e6sR85 \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

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

Delete a Payment Method

Deletes an existing payment method object.

If you delete the payment method that is set as the default one, then the most recently added payment method will be used as the new default payment method.
If you delete the last payment method then the default payment method will be set to null and, if present, the most recently added card will be set as the default card.

Arguments

PAYMENT_METHOD | string, required

Identifier of the payment method object that should be deleted.

Result

A successful request returns identifier of the deleted payment method object.

DEFINITION 

DELETE https://api.shift4.com/payment-methods/{PAYMENT_METHOD_ID}

EXAMPLE REQUEST


curl https://api.shift4.com/payment-methods/pm_8HeqP7ZurLKhBPknC5e6sR85 \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -X DELETE

EXAMPLE RESPONSE

{
    "id" : "pm_8P7OWXA5xiTS1ISnyZcum1KV"
}

List Payment Methods

Lists payment method objects for a given customer.

         

Arguments

customerId | string, required

Identifier of the customer object whose payment methods should be listed.

created | object, optional

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

  • gt - return objects created after given 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

Cursor used for pagination (getting the next page). For example, if you make a list request and receive 10 objects, where the last object has id=some-example-id - then you can make another request with startingAfterId=some-example-id to get the next page of that list.

endingBeforeId | string, optional

Cursor used for pagination (getting the previous page). For example, if you make a list request and receive 10 objects, where the first object has id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get the previous page of that list.

Result

A successful request returns a list of payment method objects.

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

DEFINITION 

GET https://api.shift4.com/payment-methods

EXAMPLE REQUEST


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

EXAMPLE RESPONSE

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

Payment Links


Payment Links is a functionality that allows you to create an URL with a simple checkout. Customers that enter this link are able to either make a single payment or initialize a subscription without visiting the merchant's webpage.

Payment link object

                   

Arguments

id | string


created | timestamp


status | string

Status of a Payment link.

It can be one of the following:

  • active - Payment link is active and functional

  • expired - Payment link expired and is no longer functional

  • deactivated - Payment link has been deactivated by merchant

  • completed - preset number of successful charges made with this payment link has been reached, it is no longer functional

  • scheduled - Payment link is yet to become active


url | string


lineItems | list of objects

A list of objects created with the payment link. It can be one of two types:

  • product - object representing a single charge made through checkout generated by the Payment link

    • name 

    • amount - amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

    • currency - currency represented as a three-letter ISO currency code.

  • subscription

    • plan - planId used to create a subscription


collectBillingAddress | boolean

If the value is true, the customer will be asked to provide the billing address.


collectShippingAddress | boolean

If the value is true, the customer will be asked to provide the shipping address.


restrictions | object

This object describes time boundaries and preset number of charges made with the Payment link

  • charges - fields limit number of successful attempts to use the Payment link and presents how many successful attempts there were

    • limit (integer) - number of preset attempts 

    • count (integer) - number of successful charges


customer | string

Customer associated with the charge or subscription created via the Payment link.


metadata | metadata object

Result

A successful request returns a Payment Link object.

EXAMPLE OBJECT

{
  "id" : "link_8v6pz2FEOvlDA80wOGhUhP8N",
  "created" : 1746021690,
  "status" : "active",
  "url" : "https://pay.shift4.com/link_8v6pz2FEOvlDA80wOGhUhP8N",
  "lineItems" : [ {
    "product" : {
      "name" : "Single Payment",
      "amount" : 100000,
      "currency" : "PLN"
    }
  } ],
  "collectBillingAddress" : true,
  "collectShippingAddress" : false,
  "restrictions" : {
    "charges" : {
      "limit" : 20,
      "count" : 0
    }
  },
  "metadata" : {
      "invoiceNumber" : "INV_1206"
  }
}

Create a new Payment link


Arguments


lineItems | list of objects, required

A list of objects created with the Payment link. It can be one of two types:

  • product - object representing a single charge made through checkout generated by the Payment link

    • name 

    • amount - amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10"

    • currency - currency represented as a three-letter ISO currency code

  • subscription

    • plan - planId used to create a subscription


collectBillingAddress | boolean, optional (default is "false")

If the value is true, the customer will be asked to provide the billing address.


collectShippingAddress | boolean, optional (default is "false")

If the value is true, the customer will be asked to provide the shipping address.


restrictions | object, optional

This object describes time boundaries and preset number of charges made with the Payment link

  • charges - fields limit number of successful attempts to use the Payment link and presents how many successful attempts there were

    • limit (integer) - number of preset attempts 

customer | string, optional

Customer associated with the charge or subscription created via the Payment link.


metadata | metadata object, optional



Result

A successful request returns a Payment Link object that represents the created Payment link.

DEFINITION

POST https://api.shift4.com/payment-links

EXAMPLE REQUEST

curl https://api.shift4.com/payment-links \
  -u sk_test_xxxx: \
  -H "Content-Type: application/json" \
  --data-raw '{
    "lineItems": [
      {
        "product": {
          "name": "Example charge",
          "amount": 1000,
          "currency": "USD"
        }
      }
    ]
  }'

EXAMPLE RESPONSE

{
  "id" : "link_8kdskX8DZ8FR6W3acYPXiyAN",
  "created" : 1747678041,
  "status" : "active",
  "url" : "https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN",
  "lineItems" : [ {
    "product" : {
      "name" : "Example charge",
      "amount" : 1000,
      "currency" : "USD"
    }
  } ],
  "collectBillingAddress" : false,
  "collectShippingAddress" : false,
  "customFields" : [ ],
  "metadata" : { }
}

Retrieve an existing Payment link

                  

Arguments


PAYMENT_LINK_ID | string, required

Result

A successful request returns a Payment Link object.

DEFINITION

GET https://api.shift4.com/payment-links/{PAYMENT_LINK_ID}

EXAMPLE REQUEST

curl https://api.shift4.com/payment-links/link_odedW8aombcWuu6VIZulYKny \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
    "id": "link_odedW8aombcWuu6VIZulYKny",
    "created": 1746025976,
    "status": "active",
    "url": "https://pay.shift4.com/link_odedW8aombcWuu6VIZulYKny",
    "lineItems": [
        {
            "product": {
                "plan": "plan_0i8adiW3GNKVC5UDsKjw6r8D"
            }
        }
    ],
    "collectBillingAddress": true,
    "collectShippingAddress": false,
    "customer": "cust_jDgssNAb33TEYCjqkMh55NtF",
    "metadata": {}
}

Update an existing Payment link


Arguments


PAYMENT_LINK_ID | string, required

lineItems | list of objects, required

A list of objects created with the Payment link. It can be one of two types:

  • product - object representing a single charge made through checkout generated by the Payment link

    • name 

    • amount - amount in minor units of a given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10"

    • currency - currency represented as a three-letter ISO currency code

  • subscription

    • plan - planId used to create a subscription


collectBillingAddress | boolean, optional

If the value is true, the customer will be asked to provide the billing address.


collectShippingAddress | boolean, optional

If the value is true, the customer will be asked to provide the shipping address.


restrictions | object, optional

This object describes time boundaries and preset number of charges made with the Payment link

  • charges - fields limit number of successful attempts to use the payment link and presents how many successful attempts there were

    • limit (integer) - number of preset attempts 


metadata | metadata object, optional



Result

A successful request returns a Payment Links object that represents the updated Payment link.

DEFINITION

POST https://api.shift4.com/payment-links/PAYMENT_LINK_ID

EXAMPLE REQUEST

curl https://api.shift4.com/payment-links/link_123RF3wsQ6Eeap9b7uF5URSr \
 -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:  \
 -H "Content-Type: application/json" \
 --data-raw '{
    "lineItems": [
        {
            "product": {
                "amount": 1000,
                "currency": "USD",
                "name": "Another example charge"
            }
        }
    ],
    "collectBillingAddress": true
}'

EXAMPLE RESPONSE

{
  "id" : "link_123RF3wsQ6Eeap9b7uF5URSr",
  "created" : 1747724812,
  "status" : "active",
  "url" : "https://pay.shift4.com/link_123RF3wsQ6Eeap9b7uF5URSr",
  "lineItems" : [ {
    "product" : {
      "name" : "Another example charge",
      "amount" : 1000,
      "currency" : "USD"
    }
  } ],
  "collectBillingAddress" : true,
  "collectShippingAddress" : false,
  "customFields" : [ ],
  "metadata" : { }

Deactivate an existing Payment link

        

Note that every new Payment link is active by default. Payment links with a limited number of charges will be automatically deactivated the moment the limit is reached.

          

Arguments

PAYMENT_LINK_ID | string, required


Result

A successful request deactivates a Payment Link object.

DEFINITION

POST https://api.shift4.com/payment-links/PAYMENT_LINK_ID/deactivate


EXAMPLE REQUEST

curl https://api.shift4.com/payment-links/link_UctAU7n0JOWcHkmRyplafj3D/deactivate \
	-u sk_test_wpjbb6WhmPkiosrwcOffQNPV: \
	-X POST

EXAMPLE RESPONSE

{
    "id": "link_UctAU7n0JOWcHkmRyplafj3D",
    "created": 1727864053,
    "status": "deactivated",
    "url": "https://pay.shift4.com/link_UctAU7n0JOWcHkmRyplafj3D",
    "lineItems": [
        {
            "product": {
                "name": "Single payment",
                "amount": 20000,
                "currency": "USD"
            }
        }
    ],
    "collectBillingAddress": true,
    "collectShippingAddress": false,
    "metadata": {}
}

Reactivate an existing Payment link

        

You cannot reactivate the Payment link once the limit of charges is reached.

          

Arguments


PAYMENT_LINK_ID | string, required


Result

A successful request reactivates a Payment Link object.

DEFINITION

POST https://api.shift4.com/payment-links/PAYMENT_LINK_ID/reactivate


EXAMPLE REQUEST

curl https://api.shift4.com/payment-links/link_UctAU7n0JOWcHkmRyplafj3D/reactivate \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X POST

EXAMPLE RESPONSE

{
    "id": "link_UctAU7n0JOWcHkmRyplafj3D",
    "created": 1727864053,
    "status": "active",
    "url": "https://pay.shift4.com/link_UctAU7n0JOWcHkmRyplafj3D",
    "lineItems": [
        {
            "product": {
                "name": "Single payment",
                "amount": 20000,
                "currency": "USD"
            }
        }
    ],
    "collectBillingAddress": true,
    "collectShippingAddress": false,
    "metadata": {}
}

List Payment links


Arguments


created | object, optional

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

  • gt - return objects created after given 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

status | string, optional

Status of a payment link.

It can be one of the following:

  • active - Payment link is active and functional

  • expired - Payment link expired and is no longer functional

  • deactivated - Payment link has been deactivated by merchant

  • completed - preset number of successful charges made with this Payment link has been reached, it is no longer functional

  • scheduled - Payment link is yet to become active



Result

A successful request returns a list of Payment Link objects.

DEFINITION

GET https://api.shift4.com/payment-links/payment-links

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
  "list" : [ {
    "id" : "link_123RF3wsQ6Eeap9b7uF5URSr",
    "created" : 1747724812,
    "status" : "active",
    "url" : "https://pay.shift4.com/link_123RF3wsQ6Eeap9b7uF5URSr",
    "lineItems" : [ {
      "product" : {
        "name" : "Another example charge",
        "amount" : 1000,
        "currency" : "USD"
      }
    } ],
    "collectBillingAddress" : true,
    "collectShippingAddress" : false,
    "customFields" : [ ],
    "metadata" : { }
  }, {
    "id" : "link_8kdskX8DZ8FR6W3acYPXiyAN",
    "created" : 1747678041,
    "status" : "active",
    "url" : "https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN",
    "lineItems" : [ {
      "product" : {
        "name" : "Example charge",
        "amount" : 1000,
        "currency" : "USD"
      }
    } ],
    "collectBillingAddress" : false,
    "collectShippingAddress" : false,
    "customFields" : [ ],
    "metadata" : { }
  }, {
    "id" : "link_odedW8aombcWuu6VIZulYKny",
    "created" : 1746025976,
    "status" : "active",
    "url" : "https://pay.shift4.com/link_odedW8aombcWuu6VIZulYKny",
    "lineItems" : [ {
      "product" : {
        "plan" : "plan_0i8adiW3GNKVC5UDsKjw6r8D"
      }
    } ],
    "collectBillingAddress" : true,
    "collectShippingAddress" : false,
    "customer" : "cust_jDgssNAb33TEYCjqkMh55NtF",
    "customFields" : [ ],
    "metadata" : { }
  } ],
  "hasMore" : true
}

Checkout session details



The checkout session contains data related to a single session and maintains a reference to the charge executed within that session, along with information regarding the success of the charge. Payment link can be associated with several sessions depending on the preset limit.

Arguments

CHARGE_ID | string, required

DEFINITION

GET https://api.shift4.com/payment-links/payment-links/checkout-sessions?charge={CHARGE_ID}

EXAMPLE REQUEST

curl "https://api.shift4.com/checkout-sessions?charge=char_qTTjFTmM6uBFHrHts9gga8Ri" \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

EXAMPLE RESPONSE

{
    "list": [
        {
            "id": "chse_wo7mzgRKMEBk21ChHLMcL8ph",
            "created": 1747726145,
            "objectType": "checkout_session",
            "lastCharge": "char_qTTjFTmM6uBFHrHts9gga8Ri",
            "paymentLink": "link_8kdskX8DZ8FR6W3acYPXiyAN"
        }
    ],
    "totalCount": 1,
    "hasMore": false
}