# Apple Pay An API request for Apple Pay allows a merchant to initiate an Apple Pay transaction, by sending a request to the Apple Pay API with the required parameters such as amount, currency, and order identifier, which will be processed, and the response will be sent back with the transaction details. Endpoint: POST /apple-pay Version: 1.0.0 Security: MerchantID ## Header parameters: - `merchant` (string, required) Unique public key provided upon registration and must be shared for identification purposes. Example: "api_pk_7b197...ba108f842" - `signature` (string, required) Request signature that allows verification of merchant authenticity on the payment gateway server. Example: "M2E3OTkyNzcz...xMmExODI4" ## Request fields (application/json): - `body` (object) — one of: - Payment: - `is_decrypted` (boolean) Indicates whether the payload received from Apple Pay was previously decrypted. - Product-based payment: - `is_decrypted` (boolean) Indicates whether the payload received from Apple Pay was previously decrypted. - Subscription payment: - `is_decrypted` (boolean) Indicates whether the payload received from Apple Pay was previously decrypted. ## Response 200 fields (application/json): - `body` (object) — one of: - Success: - `order` (object, required) Details of an order, including identifiers, timestamps, amounts, status, and customer data. - `order.order_id` (string, required) Unique order identifier, which can be used to find the payment. For the first payment, the identifier is defined by the merchant. For recurring subscription-based payments, it is generated by the Solidgate subscription service. Example: "923bb4e6-4a5f-41ec-81fb-28eb8a152e55" - `order.order_description` (string) Brief order description. Example: "Premium package" - `order.psp_order_id` (string) PSP identifier generated by Solidgate. - `order.provider_payment_id` (string) PSP identifier generated by the PSP. Value will be if the integration transmitted this data. - `order.subscription_id` (string) Unique subscription identifier. Example: "83b19018-cbc4-4df0-899a-dda84fd2705e" - `order.amount` (integer, required) Order amount in the smallest currency unit. This is the intended initial authorization amount. For instance, 1020 means 10 EUR and 20 cents. Example: 100 - `order.currency` (string, required) Three-letter ISO-4217 currency code. Example: "USD" - `order.processing_amount` (integer) Amount of the payment in the smallest currency unit as it was processed by the payment service provider. This amount may differ from the original order amount due to currency conversion or other processing factors. - `order.processing_currency` (string) Three-letter ISO-4217 currency code of the payment when it was processed by payment service provider. In some cases, it is different from the original currency. Example: "USD" - `order.marketing_amount` (integer) Order amount converted to USD, or other currency as agreed, using a publicly available rate at the payment date. This is based on the intended initial authorization amount. It should not be considered financial information, but it can be used for forecasting. - `order.marketing_currency` (string) Three-letter ISO-4217 currency code of the currency used for calculation of marketing amount. Example: "USD" - `order.refunded_amount` (integer, required) Indicates the amount that has been already refunded. - `order.status` (string, required) Status of the requested order. Enum: "processing", "3ds_verify", "refunded", "auth_ok", "auth_failed", "settle_ok", "partial_settled", "void_ok" - `order.auth_code` (string) Transaction authorization code. It can be empty if the provider does not pass a value. Example: "2w9m8" - `order.payment_type` (string) Payment type that defines if the transaction is customer-initiated (CIT) or merchant-initiated (MIT) and helps to define if a cardholder authentication can be provided. Enum: "1-click", "recurring", "retry", "installment", "rebill", "moto" - `order.payment_method` (string) Payment method used for the transaction. Enum: "apple-pay" - `order.customer_email` (string) Customer's email address. Example: "example@example.com" - `order.descriptor` (string) Identifying text that appears on a customer’s credit or debit card statement. It includes information about the transaction and helps the cardholder recognize the charge. Example: "google.com" - `order.mid` (string) Merchant identifier in Solidgate. Example: "bank-mid-1" - `order.ip_address` (string) Public IP address of the cardholder, both IPv4 and IPv6 are supported. Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error. - `order.traffic_source` (string) Identifies the marketing or acquisition channel that brought the customer to the transaction. Example: "facebook" - `order.product_id` (string) Unique product identifier. - `order.product_name` (string) Product name. - `order.customer_account_id` (string) Unique customer identifier defined by the merchant. Example: "93a1c659-288d-4d62-929d-10e241078faa" - `order.fraudulent` (boolean) Whether the merchant system has flagged this customer as suspicious. - `transaction` (object) Details of a card transaction, including identifiers, timestamps, amounts, currency, operation type, status, and other relevant data. - `transaction.id` (string, required) Unique transaction identifier. Example: "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a" - `transaction.created_at` (string, required) Datetime when the transaction was created. Example: "2025-12-27 11:45:30" - `transaction.updated_at` (string, required) Datetime when the transaction was updated. Example: "2025-12-28 11:45:30" - `transaction.amount` (integer, required) Transaction amount. Example: 100 - `transaction.currency` (string, required) Three-letter ISO-4217 currency code of the transaction. Example: "USD" - `transaction.marketing_amount` (integer) Order amount converted to USD, or other currency as agreed, using a publicly available rate at the payment date. It should not be considered financial information, but it can be used for forecasting. - `transaction.marketing_currency` (string) Three-letter ISO-4217 currency code of the currency used for calculation of marketing amount. Example: "USD" - `transaction.operation` (string, required) Type of the transaction. Enum: "recurring-auth", "refund", "resign-auth", "auth", "settle", "void", "apple-pay", "google-pay" - `transaction.status` (string, required) Status of the transaction. Enum: "processing", "success", "fail", "verify" - `transaction.authorization_type` (string) Authorization type that defines the transaction flow and capabilities. Enum: "final", "estimated", "incremental" - `transaction.scheme_transaction_id` (string) Card-scheme transaction identifier linking this transaction to the original customer-initiated payment. - `transaction.transaction_link_id` (string) Transaction link identifier (TLID) is an ID generated by Mastercard to link lifecycle activity after the original transaction. - `transaction.descriptor` (string) Identifying text that appears on a customer’s credit or debit card statement. It includes information about the transaction and helps the cardholder recognize the charge. Example: "google.com" - `transaction.billing_details` (object) Billing address details. - `transaction.billing_details.address` (string) First and second line of the billing address. - `transaction.billing_details.country` (string) Billing address country. - `transaction.billing_details.city` (string) Billing address city. - `transaction.billing_details.state` (string) ISO 3166-2 address state code of the billing address. - `transaction.billing_details.zip` (string) Billing zip/postal code. - `transaction.refund_reason` (string) Text description of the refund reason. Example: "Solidgate - Issuer Fraud Notification" - `transaction.refund_reason_code` (string) Code representing the reason for the refund. This code is used to identify the reason for both void and refund transactions operation Example: "0022" - `transaction.card_token` (object) Token associated with a card method that can be used for subsequent payments. - `transaction.card_token.token` (string, required) Token generated for a card method, enabling its use for future payments. The token is not generated for all types of payment flows. Example: "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299" - `transaction.card` (object, required) Object containing detailed information about the card used in the transaction. - `transaction.card.bank` (string) Name of the card issuer. Example: "JSC UNIVERSAL BANK" - `transaction.card.bin` (string, required) Card issuer's Bank Identification Number (BIN). Example: "444111" - `transaction.card.brand` (string) Card brand. Example: "VISA" - `transaction.card.card_exp_month` (string, required) Expiry month of the card. Example: "12" - `transaction.card.card_exp_year` (integer, required) Expiry year of the card. Example: 2028 - `transaction.card.card_holder` (string) Cardholder's name as it appears on the card, which is essential for transaction processing. Should be provided as the cardholder's name to ensure accurate cardholder information and increase conversions. For some PSPs, if not provided, it is set to John Snow. Example: "John Snow" - `transaction.card.card_type` (string) Card type. Enum: "CREDIT", "CREDIT/DEBIT", "DEBIT", "PREPAID", "CHARGE CARD", "DEFERRED DEBIT" - `transaction.card.is_reloadable` (boolean) Indicator of whether the card belongs to a reloadable program. null means the reloadable indicator is not available. Example: true - `transaction.card.card_id` (string) Unique identifier of the card used for the transaction. Example: "22733af4-f6c6-4368-b7d0-98aeb0253a57" - `transaction.card.country` (string) Card issuer's country. Example: "USA" - `transaction.card.number` (string, required) Masked card number. Example: "444111XXXXXX9435" - `transaction.card.card_token` (object) Token associated with a card method that can be used for subsequent payments. - `transaction.error` (object) Error object. - `transaction.error.code` (string, required) Gateway error code for the declined payment. Enum: "X.XX" - `transaction.error.messages` (array, required) An array containing either strings or objects that provide details about the error or status. When it is an array of strings, each string describes a separate issue. When it is an object, the object will contain key-value pairs explaining the issue in more detail. - `transaction.error.recommended_message_for_user` (string) Message with recommended next steps or additional information. Example: "The problem here lies with the data format and accuracy, validation error on the acquiring side" - `transaction.error.merchant_advice_code` (string) Merchant Advice Codes (MACs) are introduced by Mastercard to clearly communicate to merchants the reason for declining transactions, and the course of action that merchants can take. If present, the MAC contains information about why the payment failed, whether it can be retried and in some cases, the recommended duration after which it should be retried. Follow to the merchant advice codes to get recommendations to handle the value. - `transaction.payment_account_reference` (string) Payment Account Reference (PAR) is a unique, non-financial identifier for a payment account that remains consistent across card replacements. Example: "PAR_1A2B3C4D5E6F7G8H9" - `transaction.arn_code` (string) Acquirer Reference Number (ARN) assigned to transactions. Use ARN to check transaction status. - `transaction.rrn_code` (string) Retrieval Reference Number (RRN) assigned to transactions, based on the ISO 8583 standard. - `transactions` (object, required) Map of transactions where the keys are transaction identifiers. - `transactions.` (object, required) Details of a card transaction, including identifiers, timestamps, amounts, currency, operation type, status, and other relevant data. - `three_ds` (object) Information related to the processing of the payment. - `three_ds.eci` (string) Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure, digital wallet, and network token payments. Example: "05" - `three_ds.flow` (string) Specifies whether and how the customer was involved in the 3D Secure. Flow null indicates that 3D Secure authentication was not initiated for the transaction. Enum: "frictionless", "challenge", "none", "unspecified" - `three_ds.exception` (string) Strong Customer Authentication (SCA) exception type applied to the transaction. Enum: "low_value", "transaction_risk_assessment" - `routing` (object) Payment routing information. The availability of this object depends on whether routing is configured for your account. - `routing.cascade_steps` (array) Details of the attempts made to process the payment. - `routing.cascade_steps.mid` (string) Merchant identifier in Solidgate. - `routing.cascade_steps.mid_descriptor` (string) Identifying text that appears on a customer's credit or debit card statement. - `routing.cascade_steps.route_id` (string) Route identifier configured in Solidgate. - `routing.cascade_steps.cascade_number` (integer) Sequential number of the processing attempt in the routing cascade, fallback step number. Indicates which attempt in the fallback sequence was used to process the payment. - `routing.cascade_steps.segment_id` (string) Identifier of the segment used for this processing attempt in the routing configuration. Each segment represents a specific processing configuration within a route. - `antifraud_result` (object) Pre-authorization decision returned by Solidgate Antifraud. Returned only when the merchant uses Solidgate’s internal antifraud service, which excludes provider-side fraud results. - `antifraud_result.pre_auth` (string) Outcome of the real-time antifraud screening performed before the authorization request is sent. - reject - transaction declined - review - requires manual review - pass - approved to proceed Enum: "reject", "review", "pass" - `verification_result` (object) Verification results for Address Verification Service (AVS), Card Verification Value (CVV), and Account Name Inquiry (ANI), providing match status. - `verification_result.avs_result` (string) AVS result from card schemes verifies if the billing address matches with the issuing bank. It returns a value that indicates the level of match, assisting in the decision to approve, verify, or decline a transaction. Enum: "matched", "partially_matched", "not_matched", "unsupported", "unavailable", "unknown" - `verification_result.cvv_result` (string) CVV result indicates whether the CVV code entered matches the one on the card, confirming the cardholder’s possession. It helps assess transaction legitimacy and decide whether to approve, verify, or decline. Enum: "matched", "not_matched", "not_checked", "unavailable", "unknown" - `verification_result.ani` (object) ANI result from the card scheme verifies whether the cardholder name matches the issuer’s records. It helps confirm the cardholder’s identity, supporting the decision to approve, verify, or decline a transaction. - `verification_result.ani.status` (string) Outcome of the name match check performed against the issuer’s records. Enum: "performed", "not_performed", "not_supported" - `verification_result.ani.full_name_match` (string) Result of matching the full cardholder name against the issuer’s records. Enum: "matched", "partially_matched", "not_matched" - `verification_result.ani.first_name_match` (string) Result of matching the cardholder’s first name against the issuer’s records. Enum: same as `verification_result.ani.full_name_match` in "Success" (3 values) - `verification_result.ani.last_name_match` (string) Result of matching the cardholder’s last name against the issuer’s records. Enum: same as `verification_result.ani.full_name_match` in "Success" (3 values) - `chargebacks` (object) Map of chargebacks where the keys are chargeback identifiers. - `chargebacks.` (object) Information about a chargeback, including identifiers, dates, amounts, status, and the flow of the chargeback process. - `chargebacks..id` (integer, required) Unique chargeback identifier. Example: 12345 - `chargebacks..dispute_date` (string, required) Date when the chargeback was created by the issuer. Example: "2025-07-10 00:00:00" - `chargebacks..settlement_date` (string) Date when the chargeback was financially settled. Example: "2025-07-11 00:00:00" - `chargebacks..amount` (integer, required) Amount that will be deducted for the chargeback on a specific order. This amount may vary based on the user's decision to dispute a different amount. Example: 100 - `chargebacks..currency` (string, required) Three-letter ISO-4217 currency code of the chargeback amount. Example: "USD" - `chargebacks..type` (string) Current type of the chargeback. Enum: "1st_chb", "2nd_chb", "arbitration" - `chargebacks..status` (string) Status of the chargeback. Enum: "in_progress", "document_sent", "reversed", "accepted", "resolved", "resolved_reversal" - `chargebacks..reason_group` (string) Reason code group. It could be used for the segmentation and analytic purposes. Example: "Fraud" - `chargebacks..reason_code` (string) Reason code for the chargeback provided by the card scheme. Example: "10.4" - `chargebacks..reason_description` (string) Reason code description for the chargeback provided by the card scheme. Example: "Fraud – Card-Absent Environment" - `chargebacks..chargeback_flow` (array, required) Map of chargeback flows where the keys are chargeback flow identifiers. - `chargebacks..chargeback_flow.id` (integer, required) Unique chargeback flow identifier. - `chargebacks..chargeback_flow.date` (string) Datetime when the chargeback flow was created. - `chargebacks..chargeback_flow.updated_date` (string) Datetime when the chargeback flow was updated. - `chargebacks..chargeback_flow.settlement_date` (string) Date when the chargeback flow was financially settled. - `chargebacks..chargeback_flow.deadline_date` (string) Deadline for submitting a response to the dispute. This corresponds to date + n, where n is a number of calendar days set by the scheme/acquirer. - `chargebacks..chargeback_flow.amount` (integer, required) Amount involved in each stage of the chargeback process. For example, there could be two records in chargeback_flow one with an amount of 113.58 USD and another with an amount of 100 USD. - `chargebacks..chargeback_flow.dispute_amount` (integer, required) Specific amount disputed, typically in the smallest currency unit, that would be returned to the merchant if the dispute is resolved in their favor. For example, if the second chargeback was successfully disputed, the dispute_amount would be 100 USD. - `chargebacks..chargeback_flow.currency` (string, required) Three-letter ISO-4217 currency code of the chargeback amount. - `chargebacks..chargeback_flow.type` (string, required) Type of the chargeback flow. Enum: same as `chargebacks..type` in "Success" (3 values) - `chargebacks..chargeback_flow.status` (string, required) Status of the chargeback. Enum: same as `chargebacks..status` in "Success" (6 values) - `chargebacks..chargeback_flow.arn_code` (string) Acquirer Reference Number (ARN) assigned to transactions. Use ARN to check transaction status. - `device_info` (object) Information about the device used. - `device_info.user_agent` (string) Device user-agent. - `order_metadata` (object) Metadata is useful for storing additional, structured information about an order. - `pay_form` (object) Represents a payment form, including deprecated properties related to the form URL and token. - `pay_form.form_url` (string) Payment form URL created for the order. Example: "https://example.com/pay_form_url" - `pay_form.token` (string) Secure payment token representing sensitive payment method information. Example: "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299" - `payment_adviser` (object) Provides recommendations on which payment type to offer for future orders based on the card used. - `payment_adviser.advise` (string) Recommendation for which payment type to use for the given order and card. - Authentication failed: - `error` (object, required) Error object. - `error.code` (string, required) Unauthorized access due to invalid credentials. Example: "1.01" - `error.messages` (array, required) Array of error messages applied to the decline payment. Example: ["Authentication failed"] - Error: - `error` (object, required) — one of (discriminator: code): Error object. - 2.01 Invalid data: - `messages` (array, required) Array containing messages that specify why the payment was declined due to validation errors. These messages can range from an incorrect card number to an invalid security code or billing address. Example: ["Invalid data"] - 2.01 Order not found: - `messages` (object, required) Object containing key-value pairs that clarify the reason for the payment decline, particularly in cases where the requested order does not exist. - 2.04 Card brand is not supported: - `messages` (array, required) Array containing messages that specify why the payment was declined due to unsupported card brand for incremental authorization. Supported card brands include American Express (Amex), Cartes Bancaires, Diners, Discover, JCB, Mastercard, Mexico Domestic (Network MX) and Visa. Example: ["Card brand is not supported"] - X.XX: - `messages` (array, required) Array containing either strings or objects that provide details about the error or status. When it is an array of strings, each string describes a separate issue. When it is an object, the object will contain key-value pairs explaining the issue in more detail. - `recommended_message_for_user` (string) Message with recommended next steps or additional information. Example: "The user’s card balance has insufficient funds." - `error.code` (string) Gateway error code for the declined payment.