openapi: 3.0.0
info:
version: '2.0'
title: Square ApplePay GiftCardActivities API
description: 'Supercharge Square for sellers of every size. Our entire connected commerce platform from elegant hardware to a rich suite of Square APIs is yours to build with. Whether youre developing an app or composing a bespoke solution, this is the place to make it happen. '
termsOfService: https://connect.squareup.com/tos
contact:
name: Square Developer Platform
email: developers@squareup.com
url: https://squareup.com/developers
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: 'Read the official documentation here:'
url: https://docs.connect.squareup.com/
x-server-configuration:
default-environment: production
default-server: default
environments:
- name: production
servers:
- name: default
url: https://connect.squareup.com
- name: sandbox
servers:
- name: default
url: https://connect.squareupsandbox.com
- name: custom
servers:
- name: default
url: '{custom_url}'
parameters:
- name: custom_url
description: Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
type: string
example: https://connect.squareup.com
x-square-generic-error-codes:
- ACCESS_TOKEN_EXPIRED
- ACCESS_TOKEN_REVOKED
- API_VERSION_INCOMPATIBLE
- APPLICATION_DISABLED
- ARRAY_EMPTY
- ARRAY_LENGTH_TOO_LONG
- ARRAY_LENGTH_TOO_SHORT
- BAD_CERTIFICATE
- BAD_GATEWAY
- BAD_REQUEST
- CONFLICT
- CONFLICTING_PARAMETERS
- CURRENCY_MISMATCH
- EXPECTED_ARRAY
- EXPECTED_BASE64_ENCODED_BYTE_ARRAY
- EXPECTED_BOOLEAN
- EXPECTED_FLOAT
- EXPECTED_INTEGER
- EXPECTED_JSON_BODY
- EXPECTED_MAP
- EXPECTED_OBJECT
- EXPECTED_STRING
- FORBIDDEN
- GATEWAY_TIMEOUT
- GONE
- IDEMPOTENCY_KEY_REUSED
- INCORRECT_TYPE
- INSUFFICIENT_SCOPES
- INTERNAL_SERVER_ERROR
- INVALID_ARRAY_VALUE
- INVALID_CONTENT_TYPE
- INVALID_CURSOR
- INVALID_ENUM_VALUE
- INVALID_FORM_VALUE
- INVALID_SORT_ORDER
- INVALID_SQUARE_VERSION_FORMAT
- INVALID_TIME
- INVALID_TIME_RANGE
- INVALID_VALUE
- LOCATION_MISMATCH
- MAP_KEY_LENGTH_TOO_LONG
- MAP_KEY_LENGTH_TOO_SHORT
- MERCHANT_SUBSCRIPTION_NOT_FOUND
- METHOD_NOT_ALLOWED
- MISSING_REQUIRED_PARAMETER
- NOT_ACCEPTABLE
- NOT_FOUND
- NOT_IMPLEMENTED
- NO_FIELDS_SET
- RATE_LIMITED
- REQUEST_ENTITY_TOO_LARGE
- REQUEST_TIMEOUT
- SANDBOX_NOT_SUPPORTED
- SERVICE_UNAVAILABLE
- TOO_MANY_MAP_ENTRIES
- UNAUTHORIZED
- UNEXPECTED_VALUE
- UNKNOWN_BODY_PARAMETER
- UNKNOWN_QUERY_PARAMETER
- UNPROCESSABLE_ENTITY
- UNSUPPORTED_MEDIA_TYPE
- V1_ACCESS_TOKEN
- V1_APPLICATION
- VALUE_EMPTY
- VALUE_REGEX_MISMATCH
- VALUE_TOO_HIGH
- VALUE_TOO_LONG
- VALUE_TOO_LOW
- VALUE_TOO_SHORT
servers:
- url: https://connect.squareup.com
variables: {}
tags:
- name: GiftCardActivities
paths:
/v2/gift-cards/activities:
get:
tags:
- GiftCardActivities
summary: Square List Gift Card Activities
operationId: ListGiftCardActivities
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
description: 'Lists gift card activities. By default, you get gift card activities for all
gift cards in the seller''s account. You can optionally specify query parameters to
filter the list. For example, you can get a list of gift card activities for a gift card,
for all gift cards in a specific region, or for activities within a time window.'
x-release-status: PUBLIC
security:
- oauth2:
- GIFTCARDS_READ
parameters:
- name: gift_card_id
description: "If a gift card ID is provided, the endpoint returns activities related \nto the specified gift card. Otherwise, the endpoint returns all gift card activities for \nthe seller."
schema:
type: string
in: query
required: false
- name: type
description: "If a [type](entity:GiftCardActivityType) is provided, the endpoint returns gift card activities of the specified type. \nOtherwise, the endpoint returns all types of gift card activities."
schema:
type: string
in: query
required: false
- name: location_id
description: "If a location ID is provided, the endpoint returns gift card activities for the specified location. \nOtherwise, the endpoint returns gift card activities for all locations."
schema:
type: string
in: query
required: false
- name: begin_time
description: 'The timestamp for the beginning of the reporting period, in RFC 3339 format.
This start time is inclusive. The default value is the current time minus one year.'
schema:
type: string
in: query
required: false
- name: end_time
description: 'The timestamp for the end of the reporting period, in RFC 3339 format.
This end time is inclusive. The default value is the current time.'
schema:
type: string
in: query
required: false
- name: limit
description: "If a limit is provided, the endpoint returns the specified number \nof results (or fewer) per page. The maximum value is 100. The default value is 50.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
schema:
type: integer
in: query
required: false
- name: cursor
description: 'A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, the endpoint returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).'
schema:
type: string
in: query
required: false
- name: sort_order
description: 'The order in which the endpoint returns the activities, based on `created_at`.
- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default).'
schema:
type: string
in: query
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListGiftCardActivitiesResponse'
post:
tags:
- GiftCardActivities
summary: Square Create Gift Card Activity
operationId: CreateGiftCardActivity
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
description: 'Creates a gift card activity to manage the balance or state of a [gift card](entity:GiftCard).
For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use.'
x-release-status: PUBLIC
security:
- oauth2:
- GIFTCARDS_WRITE
parameters: []
requestBody:
required: true
description: 'An object containing the fields to POST for the request.
See the corresponding object definition for field details.'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGiftCardActivityRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGiftCardActivityResponse'
x-endpoint-errors:
- error-code: INSUFFICIENT_FUNDS
- error-code: PAYMENT_LIMIT_EXCEEDED
- error-code: REFUND_AMOUNT_INVALID
- error-code: TEMPORARY_ERROR
components:
schemas:
GiftCardActivityAdjustDecrementReason:
type: string
enum:
- SUSPICIOUS_ACTIVITY
- BALANCE_ACCIDENTALLY_INCREASED
- SUPPORT_ISSUE
- PURCHASE_WAS_REFUNDED
x-enum-elements:
- name: SUSPICIOUS_ACTIVITY
description: 'The balance was decreased because the seller detected suspicious or fraudulent activity
on the gift card.'
- name: BALANCE_ACCIDENTALLY_INCREASED
description: The balance was decreased to reverse an unintentional balance increase.
- name: SUPPORT_ISSUE
description: The balance was decreased to accommodate support issues.
- name: PURCHASE_WAS_REFUNDED
description: 'The balance was decreased because the order used to purchase or reload the
gift card was refunded.'
description: Indicates the reason for deducting money from a [gift card](entity:GiftCard).
x-release-status: PUBLIC
GiftCardActivityAdjustDecrement:
type: object
description: Represents details about an `ADJUST_DECREMENT` [gift card activity type](entity:GiftCardActivityType).
x-release-status: PUBLIC
required:
- amount_money
- reason
properties:
amount_money:
$ref: '#/components/schemas/Money'
description: The amount deducted from the gift card balance. This value is a positive integer.
reason:
$ref: '#/components/schemas/GiftCardActivityAdjustDecrementReason'
description: 'The reason the gift card balance was adjusted.
See [Reason](#type-reason) for possible values'
ErrorCategory:
type: string
enum:
- API_ERROR
- AUTHENTICATION_ERROR
- INVALID_REQUEST_ERROR
- RATE_LIMIT_ERROR
- PAYMENT_METHOD_ERROR
- REFUND_ERROR
- MERCHANT_SUBSCRIPTION_ERROR
- EXTERNAL_VENDOR_ERROR
x-enum-elements:
- name: API_ERROR
description: An error occurred with the Connect API itself.
- name: AUTHENTICATION_ERROR
description: 'An authentication error occurred. Most commonly, the request had
a missing, malformed, or otherwise invalid `Authorization` header.'
- name: INVALID_REQUEST_ERROR
description: 'The request was invalid. Most commonly, a required parameter was
missing, or a provided parameter had an invalid value.'
- name: RATE_LIMIT_ERROR
description: 'Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests
to Square APIs in a short period of time.
Your application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)
schedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule.'
- name: PAYMENT_METHOD_ERROR
description: 'An error occurred while processing a payment method. Most commonly,
the details of the payment method were invalid (such as a card''s CVV
or expiration date).'
- name: REFUND_ERROR
description: An error occurred while attempting to process a refund.
- name: MERCHANT_SUBSCRIPTION_ERROR
description: An error occurred when checking a merchant subscription status
- name: EXTERNAL_VENDOR_ERROR
description: An error that is returned from an external vendor's API
description: 'Indicates which high-level category of error has occurred during a
request to the Connect API.'
x-release-status: PUBLIC
ErrorCode:
type: string
enum:
- INTERNAL_SERVER_ERROR
- UNAUTHORIZED
- ACCESS_TOKEN_EXPIRED
- ACCESS_TOKEN_REVOKED
- CLIENT_DISABLED
- FORBIDDEN
- INSUFFICIENT_SCOPES
- APPLICATION_DISABLED
- V1_APPLICATION
- V1_ACCESS_TOKEN
- CARD_PROCESSING_NOT_ENABLED
- MERCHANT_SUBSCRIPTION_NOT_FOUND
- BAD_REQUEST
- MISSING_REQUIRED_PARAMETER
- INCORRECT_TYPE
- INVALID_TIME
- INVALID_TIME_RANGE
- INVALID_VALUE
- INVALID_CURSOR
- UNKNOWN_QUERY_PARAMETER
- CONFLICTING_PARAMETERS
- EXPECTED_JSON_BODY
- INVALID_SORT_ORDER
- VALUE_REGEX_MISMATCH
- VALUE_TOO_SHORT
- VALUE_TOO_LONG
- VALUE_TOO_LOW
- VALUE_TOO_HIGH
- VALUE_EMPTY
- ARRAY_LENGTH_TOO_LONG
- ARRAY_LENGTH_TOO_SHORT
- ARRAY_EMPTY
- EXPECTED_BOOLEAN
- EXPECTED_INTEGER
- EXPECTED_FLOAT
- EXPECTED_STRING
- EXPECTED_OBJECT
- EXPECTED_ARRAY
- EXPECTED_MAP
- EXPECTED_BASE64_ENCODED_BYTE_ARRAY
- INVALID_ARRAY_VALUE
- INVALID_ENUM_VALUE
- INVALID_CONTENT_TYPE
- INVALID_FORM_VALUE
- CUSTOMER_NOT_FOUND
- ONE_INSTRUMENT_EXPECTED
- NO_FIELDS_SET
- TOO_MANY_MAP_ENTRIES
- MAP_KEY_LENGTH_TOO_SHORT
- MAP_KEY_LENGTH_TOO_LONG
- CUSTOMER_MISSING_NAME
- CUSTOMER_MISSING_EMAIL
- INVALID_PAUSE_LENGTH
- INVALID_DATE
- UNSUPPORTED_COUNTRY
- UNSUPPORTED_CURRENCY
- APPLE_TTP_PIN_TOKEN
- CARD_EXPIRED
- INVALID_EXPIRATION
- INVALID_EXPIRATION_YEAR
- INVALID_EXPIRATION_DATE
- UNSUPPORTED_CARD_BRAND
- UNSUPPORTED_ENTRY_METHOD
- INVALID_ENCRYPTED_CARD
- INVALID_CARD
- PAYMENT_AMOUNT_MISMATCH
- GENERIC_DECLINE
- CVV_FAILURE
- ADDRESS_VERIFICATION_FAILURE
- INVALID_ACCOUNT
- CURRENCY_MISMATCH
- INSUFFICIENT_FUNDS
- INSUFFICIENT_PERMISSIONS
- CARDHOLDER_INSUFFICIENT_PERMISSIONS
- INVALID_LOCATION
- TRANSACTION_LIMIT
- VOICE_FAILURE
- PAN_FAILURE
- EXPIRATION_FAILURE
- CARD_NOT_SUPPORTED
- INVALID_PIN
- MISSING_PIN
- MISSING_ACCOUNT_TYPE
- INVALID_POSTAL_CODE
- INVALID_FEES
- MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED
- PAYMENT_LIMIT_EXCEEDED
- GIFT_CARD_AVAILABLE_AMOUNT
- ACCOUNT_UNUSABLE
- BUYER_REFUSED_PAYMENT
- DELAYED_TRANSACTION_EXPIRED
- DELAYED_TRANSACTION_CANCELED
- DELAYED_TRANSACTION_CAPTURED
- DELAYED_TRANSACTION_FAILED
- CARD_TOKEN_EXPIRED
- CARD_TOKEN_USED
- AMOUNT_TOO_HIGH
- UNSUPPORTED_INSTRUMENT_TYPE
- REFUND_AMOUNT_INVALID
- REFUND_ALREADY_PENDING
- PAYMENT_NOT_REFUNDABLE
- PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE
- REFUND_DECLINED
- INSUFFICIENT_PERMISSIONS_FOR_REFUND
- INVALID_CARD_DATA
- SOURCE_USED
- SOURCE_EXPIRED
- UNSUPPORTED_LOYALTY_REWARD_TIER
- LOCATION_MISMATCH
- IDEMPOTENCY_KEY_REUSED
- UNEXPECTED_VALUE
- SANDBOX_NOT_SUPPORTED
- INVALID_EMAIL_ADDRESS
- INVALID_PHONE_NUMBER
- CHECKOUT_EXPIRED
- BAD_CERTIFICATE
- INVALID_SQUARE_VERSION_FORMAT
- API_VERSION_INCOMPATIBLE
- CARD_PRESENCE_REQUIRED
- UNSUPPORTED_SOURCE_TYPE
- CARD_MISMATCH
- PLAID_ERROR
- PLAID_ERROR_ITEM_LOGIN_REQUIRED
- PLAID_ERROR_RATE_LIMIT
- CARD_DECLINED
- VERIFY_CVV_FAILURE
- VERIFY_AVS_FAILURE
- CARD_DECLINED_CALL_ISSUER
- CARD_DECLINED_VERIFICATION_REQUIRED
- BAD_EXPIRATION
- CHIP_INSERTION_REQUIRED
- ALLOWABLE_PIN_TRIES_EXCEEDED
- RESERVATION_DECLINED
- UNKNOWN_BODY_PARAMETER
- NOT_FOUND
- APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
- METHOD_NOT_ALLOWED
- NOT_ACCEPTABLE
- REQUEST_TIMEOUT
- CONFLICT
- GONE
- REQUEST_ENTITY_TOO_LARGE
- UNSUPPORTED_MEDIA_TYPE
- UNPROCESSABLE_ENTITY
- RATE_LIMITED
- NOT_IMPLEMENTED
- BAD_GATEWAY
- SERVICE_UNAVAILABLE
- TEMPORARY_ERROR
- GATEWAY_TIMEOUT
x-enum-elements:
- name: INTERNAL_SERVER_ERROR
description: A general server error occurred.
error-category: API_ERROR
- name: UNAUTHORIZED
description: A general authorization error occurred.
error-category: AUTHENTICATION_ERROR
- name: ACCESS_TOKEN_EXPIRED
description: The provided access token has expired.
error-category: AUTHENTICATION_ERROR
- name: ACCESS_TOKEN_REVOKED
description: The provided access token has been revoked.
error-category: AUTHENTICATION_ERROR
- name: CLIENT_DISABLED
description: The provided client has been disabled.
error-category: AUTHENTICATION_ERROR
- name: FORBIDDEN
description: A general access error occurred.
error-category: AUTHENTICATION_ERROR
- name: INSUFFICIENT_SCOPES
description: 'The provided access token does not have permission
to execute the requested action.'
error-category: AUTHENTICATION_ERROR
- name: APPLICATION_DISABLED
description: The calling application was disabled.
error-category: INVALID_REQUEST_ERROR
- name: V1_APPLICATION
description: 'The calling application was created prior to
2016-03-30 and is not compatible with v2 Square API calls.'
error-category: INVALID_REQUEST_ERROR
- name: V1_ACCESS_TOKEN
description: 'The calling application is using an access token
created prior to 2016-03-30 and is not compatible with v2 Square API
calls.'
error-category: INVALID_REQUEST_ERROR
- name: CARD_PROCESSING_NOT_ENABLED
description: 'The location provided in the API call is not
enabled for credit card processing.'
error-category: INVALID_REQUEST_ERROR
- name: MERCHANT_SUBSCRIPTION_NOT_FOUND
description: A required subscription was not found for the merchant
error-category: MERCHANT_SUBSCRIPTION_ERROR
- name: BAD_REQUEST
description: A general error occurred with the request.
error-category: INVALID_REQUEST_ERROR
- name: MISSING_REQUIRED_PARAMETER
description: 'The request is missing a required path, query, or
body parameter.'
error-category: INVALID_REQUEST_ERROR
- name: INCORRECT_TYPE
description: 'The value provided in the request is the wrong
type. For example, a string instead of an integer.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_TIME
description: 'Formatting for the provided time value is
incorrect.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_TIME_RANGE
description: 'The time range provided in the request is invalid.
For example, the end time is before the start time.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_VALUE
description: 'The provided value is invalid. For example,
including `%` in a phone number.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_CURSOR
description: 'The pagination cursor included in the request is
invalid.'
error-category: INVALID_REQUEST_ERROR
- name: UNKNOWN_QUERY_PARAMETER
description: 'The query parameters provided is invalid for the
requested endpoint.'
error-category: INVALID_REQUEST_ERROR
- name: CONFLICTING_PARAMETERS
description: 'One or more of the request parameters conflict with
each other.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_JSON_BODY
description: The request body is not a JSON object.
error-category: INVALID_REQUEST_ERROR
- name: INVALID_SORT_ORDER
description: 'The provided sort order is not a valid key.
Currently, sort order must be `ASC` or `DESC`.'
error-category: INVALID_REQUEST_ERROR
- name: VALUE_REGEX_MISMATCH
description: 'The provided value does not match an expected
regular expression.'
error-category: INVALID_REQUEST_ERROR
- name: VALUE_TOO_SHORT
description: 'The provided string value is shorter than the
minimum length allowed.'
error-category: INVALID_REQUEST_ERROR
- name: VALUE_TOO_LONG
description: 'The provided string value is longer than the
maximum length allowed.'
error-category: INVALID_REQUEST_ERROR
- name: VALUE_TOO_LOW
description: 'The provided value is less than the supported
minimum.'
error-category: INVALID_REQUEST_ERROR
- name: VALUE_TOO_HIGH
description: 'The provided value is greater than the supported
maximum.'
error-category: INVALID_REQUEST_ERROR
- name: VALUE_EMPTY
description: 'The provided value has a default (empty) value
such as a blank string.'
error-category: INVALID_REQUEST_ERROR
- name: ARRAY_LENGTH_TOO_LONG
description: The provided array has too many elements.
error-category: INVALID_REQUEST_ERROR
- name: ARRAY_LENGTH_TOO_SHORT
description: The provided array has too few elements.
error-category: INVALID_REQUEST_ERROR
- name: ARRAY_EMPTY
description: The provided array is empty.
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_BOOLEAN
description: 'The endpoint expected the provided value to be a
boolean.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_INTEGER
description: 'The endpoint expected the provided value to be an
integer.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_FLOAT
description: 'The endpoint expected the provided value to be a
float.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_STRING
description: 'The endpoint expected the provided value to be a
string.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_OBJECT
description: 'The endpoint expected the provided value to be a
JSON object.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_ARRAY
description: 'The endpoint expected the provided value to be an
array or list.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_MAP
description: 'The endpoint expected the provided value to be a
map or associative array.'
error-category: INVALID_REQUEST_ERROR
- name: EXPECTED_BASE64_ENCODED_BYTE_ARRAY
description: 'The endpoint expected the provided value to be an
array encoded in base64.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_ARRAY_VALUE
description: 'One or more objects in the array does not match the
array type.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_ENUM_VALUE
description: 'The provided static string is not valid for the
field.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_CONTENT_TYPE
description: Invalid content type header.
error-category: INVALID_REQUEST_ERROR
- name: INVALID_FORM_VALUE
description: 'Only relevant for applications created prior to
2016-03-30. Indicates there was an error while parsing form values.'
error-category: INVALID_REQUEST_ERROR
- name: CUSTOMER_NOT_FOUND
description: The provided customer id can't be found in the merchant's customers list.
error-category: INVALID_REQUEST_ERROR
- name: ONE_INSTRUMENT_EXPECTED
description: A general error occurred.
error-category: INVALID_REQUEST_ERROR
- name: NO_FIELDS_SET
description: A general error occurred.
error-category: INVALID_REQUEST_ERROR
- name: TOO_MANY_MAP_ENTRIES
description: Too many entries in the map field.
error-category: INVALID_REQUEST_ERROR
- name: MAP_KEY_LENGTH_TOO_SHORT
description: The length of one of the provided keys in the map is too short.
error-category: INVALID_REQUEST_ERROR
- name: MAP_KEY_LENGTH_TOO_LONG
description: The length of one of the provided keys in the map is too long.
error-category: INVALID_REQUEST_ERROR
- name: CUSTOMER_MISSING_NAME
description: The provided customer does not have a recorded name.
error-category: INVALID_REQUEST_ERROR
- name: CUSTOMER_MISSING_EMAIL
description: The provided customer does not have a recorded email.
error-category: INVALID_REQUEST_ERROR
- name: INVALID_PAUSE_LENGTH
description: The subscription cannot be paused longer than the duration of the current phase.
error-category: INVALID_REQUEST_ERROR
- name: INVALID_DATE
description: The subscription cannot be paused/resumed on the given date.
error-category: INVALID_REQUEST_ERROR
- name: UNSUPPORTED_COUNTRY
description: The API request references an unsupported country.
error-category: INVALID_REQUEST_ERROR
- name: UNSUPPORTED_CURRENCY
description: The API request references an unsupported currency.
error-category: INVALID_REQUEST_ERROR
- name: APPLE_TTP_PIN_TOKEN
description: 'The payment was declined by the card issuer during an Apple Tap to Pay (TTP)
transaction with a request for the card''s PIN. This code will be returned alongside
`CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an
issuer-provided token in the `details` field that is needed to initiate the PIN
collection flow on the iOS device.'
error-category: PAYMENT_METHOD_ERROR
- name: CARD_EXPIRED
description: The card issuer declined the request because the card is expired.
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_EXPIRATION
description: 'The expiration date for the payment card is invalid. For example,
it indicates a date in the past.'
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_EXPIRATION_YEAR
description: 'The expiration year for the payment card is invalid. For example,
it indicates a year in the past or contains invalid characters.'
error-category: INVALID_REQUEST_ERROR
- name: INVALID_EXPIRATION_DATE
description: 'The expiration date for the payment card is invalid. For example,
it contains invalid characters.'
error-category: INVALID_REQUEST_ERROR
- name: UNSUPPORTED_CARD_BRAND
description: The credit card provided is not from a supported issuer.
error-category: PAYMENT_METHOD_ERROR
- name: UNSUPPORTED_ENTRY_METHOD
description: The entry method for the credit card (swipe, dip, tap) is not supported.
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_ENCRYPTED_CARD
description: The encrypted card information is invalid.
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_CARD
description: The credit card cannot be validated based on the provided details.
error-category: PAYMENT_METHOD_ERROR
- name: PAYMENT_AMOUNT_MISMATCH
description: 'The payment was declined because there was a payment amount mismatch.
The money amount Square was expecting does not match the amount provided.'
error-category: PAYMENT_METHOD_ERROR
- name: GENERIC_DECLINE
description: 'Square received a decline without any additional information.
If the payment information seems correct, the buyer can contact their
issuer to ask for more information.'
error-category: PAYMENT_METHOD_ERROR
- name: CVV_FAILURE
description: The card issuer declined the request because the CVV value is invalid.
error-category: PAYMENT_METHOD_ERROR
- name: ADDRESS_VERIFICATION_FAILURE
description: The card issuer declined the request because the postal code is invalid.
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_ACCOUNT
description: The issuer was not able to locate the account on record.
error-category: PAYMENT_METHOD_ERROR
- name: CURRENCY_MISMATCH
description: 'The currency associated with the payment is not valid for the provided
funding source. For example, a gift card funded in USD cannot be used to process
payments in GBP.'
error-category: PAYMENT_METHOD_ERROR
- name: INSUFFICIENT_FUNDS
description: The funding source has insufficient funds to cover the payment.
error-category: PAYMENT_METHOD_ERROR
- name: INSUFFICIENT_PERMISSIONS
description: 'The Square account does not have the permissions to accept
this payment. For example, Square may limit which merchants are
allowed to receive gift card payments.'
error-category: PAYMENT_METHOD_ERROR
- name: CARDHOLDER_INSUFFICIENT_PERMISSIONS
description: 'The card issuer has declined the transaction due to restrictions on where the card can be used.
For example, a gift card is limited to a single merchant.'
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_LOCATION
description: 'The Square account cannot take payments in the specified region.
A Square account can take payments only from the region where the account was created.'
error-category: PAYMENT_METHOD_ERROR
- name: TRANSACTION_LIMIT
description: 'The card issuer has determined the payment amount is either too high or too low.
The API returns the error code mostly for credit cards (for example, the card reached
the credit limit). However, sometimes the issuer bank can indicate the error for debit
or prepaid cards (for example, card has insufficient funds).'
error-category: PAYMENT_METHOD_ERROR
- name: VOICE_FAILURE
description: The card issuer declined the request because the issuer requires voice authorization from the cardholder. The seller should ask the customer to contact the card issuing bank to authorize the payment.
error-category: PAYMENT_METHOD_ERROR
- name: PAN_FAILURE
description: 'The specified card number is invalid. For example, it is of
incorrect length or is incorrectly formatted.'
error-category: PAYMENT_METHOD_ERROR
- name: EXPIRATION_FAILURE
description: 'The card expiration date is either invalid or indicates that the
card is expired.'
error-category: PAYMENT_METHOD_ERROR
- name: CARD_NOT_SUPPORTED
description: 'The card is not supported either in the geographic region or by
the [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC).'
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_PIN
description: The card issuer declined the request because the PIN is invalid.
error-category: PAYMENT_METHOD_ERROR
- name: MISSING_PIN
description: The payment is missing a required PIN.
error-category: PAYMENT_METHOD_ERROR
- name: MISSING_ACCOUNT_TYPE
description: The payment is missing a required ACCOUNT_TYPE parameter.
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_POSTAL_CODE
description: The postal code is incorrectly formatted.
error-category: PAYMENT_METHOD_ERROR
- name: INVALID_FEES
description: The app_fee_money on a payment is too high.
error-category: PAYMENT_METHOD_ERROR
- name: MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED
description: The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.
error-category: PAYMENT_METHOD_ERROR
- name: PAYMENT_LIMIT_EXCEEDED
description: Square declined the request because the payment amount exceeded the processing limit for this merchant.
error-category: PAYMENT_METHOD_ERROR
- name: GIFT_CARD_AVAILABLE_AMOUNT
description: 'When a Gift Card is a payment source, you can allow taking a partial payment
by adding the `accept_partial_authorization` parameter in the request.
However, taking such a partial payment does not work if your request also includes
`tip_money`, `app_fee_money`, or both. Square declines such payments and returns
the `GIFT_CARD_AVAILABLE_AMOUNT` error.
For more information, see
[CreatePayment errors (ad
# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/openapi/square-giftcardactivities-api-openapi.yml