# Spreedly Documentation ## Guides - [Overview](https://developer.spreedly.com/docs/overview.md) - [Merchant onboarding](https://developer.spreedly.com/docs/merchant-onboarding-guide.md) - [Implementation guide](https://developer.spreedly.com/docs/onboarding-guide.md) - [Create environments and access secrets](https://developer.spreedly.com/docs/create-environments-and-access-secrets.md) - [Add gateways and receivers](https://developer.spreedly.com/docs/create-gateways-and-receivers.md) - [Collect payment methods](https://developer.spreedly.com/docs/create-payment-methods.md) - [Run transactions](https://developer.spreedly.com/docs/create-transactions.md) - [Using payment methods](https://developer.spreedly.com/docs/using-payment-methods.md) - [Testing & troubleshooting](https://developer.spreedly.com/docs/testing.md) - [Test data](https://developer.spreedly.com/docs/test-data.md) - [Troubleshooting](https://developer.spreedly.com/docs/troubleshooting.md) - [IP addresses](https://developer.spreedly.com/docs/ip-addresses.md) - [Sample applications](https://developer.spreedly.com/docs/sample-applications.md) - [Signed requests](https://developer.spreedly.com/docs/signed-requests.md) - [Composer](https://developer.spreedly.com/docs/composer.md) - [Workflow user guide](https://developer.spreedly.com/docs/workflow-user-guide.md) - [Routing rules guide](https://developer.spreedly.com/docs/routing-rules-user-guide.md) - [Recover user guide](https://developer.spreedly.com/docs/recover-user-guide.md) - [API implementation](https://developer.spreedly.com/docs/api-implementation.md) - [Normalized request and response fields](https://developer.spreedly.com/docs/normalized-request-and-response-fields.md) - [Normalized response values](https://developer.spreedly.com/docs/normalized-values.md) - [Collect payment information](https://developer.spreedly.com/docs/collect-payment-information.md) - [iFrame payment form](https://developer.spreedly.com/docs/iframe-payment-form.md) - [iFrame API lifecycle](https://developer.spreedly.com/docs/iframe-api-lifecycle.md): API docs for version 1 of the Spreedly iFrame Javascript API. - [iFrame API ThreeDS lifecycle](https://developer.spreedly.com/docs/iframe-api-threeds-lifecycle.md): API docs for version 1 of the Spreedly iFrame Javascript API. - [iFrame tokenization](https://developer.spreedly.com/docs/iframe-tokenization.md): API docs for version 1 of the Spreedly iFrame Javascript API. - [iFrame recache](https://developer.spreedly.com/docs/iframe-recache.md): API docs for version 1 of the Spreedly iFrame Javascript API - [iFrame UI](https://developer.spreedly.com/docs/iframe-ui.md): Configuring your user interface, implementing Spreedly's iFrame — API docs for version 1 of the Spreedly iFrame Javascript API - [iFrame events](https://developer.spreedly.com/docs/iframe-events.md): API docs for version 1 of the Spreedly iFrame Javascript API - [iFrame testing](https://developer.spreedly.com/docs/iframe-testing.md): API docs for version 1 of the Spreedly iFrame Javascript API - [iFrame plugins](https://developer.spreedly.com/docs/iframe-plugins.md): API docs for version 1 of the Spreedly iFrame Javascript API - [Securing iFrame](https://developer.spreedly.com/docs/securing-iframe.md): Understanding script security best-practices and requirements to maintain compliance with PCI-DSS 4.0 - [Step-by-Step: Using Certificates for Enhanced iFrame Security](https://developer.spreedly.com/docs/using-certificates-iframe-security.md): These instructions guide you through the process of generating the values you'll need in order to initialize secure tokenization on Spreedly iFrame. - [Express payment form](https://developer.spreedly.com/docs/express-payment-form.md) - [Express API lifecycle](https://developer.spreedly.com/docs/express-api-lifecycle.md): API documentation for version 2 and version 3 of the Spreedly Express Javascript API. - [Express configuration](https://developer.spreedly.com/docs/express-configuration.md): API documentation for version 2 and version 3 of the Spreedly Express Javascript API. - [Express callbacks](https://developer.spreedly.com/docs/express-callbacks.md): API documentation for version 2 and version 3 of the Spreedly Express Javascript API. - [Securing Express](https://developer.spreedly.com/docs/securing-express.md): Understanding Express security and requirements to maintain compliance with PCI-DSS 4.0 - [Javascript API](https://developer.spreedly.com/docs/javascript-api.md): There are a variety of ways to send payment data to Spreedly. We recommend the iFrame or Express to incur minimal PCI scope. - [Direct API](https://developer.spreedly.com/docs/direct-api.md): There are a variety of ways to send payment data to Spreedly. We recommend using the iFrame payment form or Spreedly Express to incur minimal PCI scope. - [The Spreedly app](https://developer.spreedly.com/docs/the-spreedly-app.md): Read more about setting up your payment environments and reviewing transaction performance in the Spreedly application. - [Your account](https://developer.spreedly.com/docs/your-account.md): Understand important concepts that will help you navigate your account and structure your company's access to Spreedly. - [Role-based access control (RBAC)](https://developer.spreedly.com/docs/rbac.md) - [Reporting](https://developer.spreedly.com/docs/reporting.md): This guide provides an overview on the standard reports and analytics - [Using Spreedly with LLMs and AI](https://developer.spreedly.com/docs/using-spreedly-with-llms-and-ai.md) - [Advanced Vault](https://developer.spreedly.com/docs/advanced-vault.md) - [Lifecycle Management](https://developer.spreedly.com/docs/account-updater.md) - [Network tokenization](https://developer.spreedly.com/docs/network-tokenization.md) - [BIN Metadata](https://developer.spreedly.com/docs/bin-metadata.md) - [Advanced Vault feature onboarding form](https://developer.spreedly.com/docs/advanced-vault-feature-onboarding-form.md) - [Advanced Vault for Merchant Aggregators](https://developer.spreedly.com/docs/advanced-vault-for-merchant-aggregators.md) - [Just in Time Lifecycle Management API](https://developer.spreedly.com/docs/just-in-time-lifecycle-management-api.md) - [Managing the vault](https://developer.spreedly.com/docs/migrations.md) - [Importing payment methods](https://developer.spreedly.com/docs/importing-payment-methods.md) - [Exporting payment methods](https://developer.spreedly.com/docs/exporting-payment-methods.md) - [Third-party vaulting](https://developer.spreedly.com/docs/third-party-vaulting.md) - [Credit card fingerprints](https://developer.spreedly.com/docs/credit-card-fingerprints.md): Fingerprinting assigns a randomly generated identifier to cards that share the same number (PAN), making it easy to identify when multiple payment methods represent the same underlying card. This is useful for merchants in a variety of scenarios, including loyalty programs, anomalous activity detection, and recognizing individual customers across different channels. - [Personal data redaction](https://developer.spreedly.com/docs/personal-data-redaction.md) - [Stored Credentials](https://developer.spreedly.com/docs/stored-credentials.md) - [Marketplace](https://developer.spreedly.com/docs/marketplace.md) - [Gateway user guide](https://developer.spreedly.com/docs/gateway-user-guide.md) - [S1 Certification - Processors](https://developer.spreedly.com/docs/spreedly-one-certification.md) - [Payment Method Distribution](https://developer.spreedly.com/docs/payment-method-distribution.md) - [Single card export](https://developer.spreedly.com/docs/single-card.md) - [Batch export](https://developer.spreedly.com/docs/batch-export.md) - [Receiver variables](https://developer.spreedly.com/docs/receiver-variables.md) - [Receiver functions](https://developer.spreedly.com/docs/receiver-functions.md) - [Supported payment methods](https://developer.spreedly.com/docs/supported-payment-methods.md) - [Apple Pay](https://developer.spreedly.com/docs/apple-pay.md) - [Third Party Apple Pay](https://developer.spreedly.com/docs/third-party-apple-pay.md) - [Google Pay](https://developer.spreedly.com/docs/google-pay.md) - [Third Party Google Pay](https://developer.spreedly.com/docs/third-party-google-pay.md) - [PayPal Offsite Payments](https://developer.spreedly.com/docs/paypal-commerce-platform-offsite-payments.md) - [Stripe APM offsite payments](https://developer.spreedly.com/docs/stripe-apm-offsite-payments.md) - [ACH payments](https://developer.spreedly.com/docs/ach-payments.md) - [Click to Pay](https://developer.spreedly.com/docs/click-to-pay.md) - [Paze](https://developer.spreedly.com/docs/paze.md): Offer Paze in your checkout via Spreedly - [Syncing your gateway transaction](https://developer.spreedly.com/docs/syncing-your-gateway-transaction.md) - [Account Funding Transactions (AFT)](https://developer.spreedly.com/docs/account-funding-transactions-aft.md) - [Spreedly 3DS solutions](https://developer.spreedly.com/docs/3ds-solutions.md) - [Introduction to Spreedly 3DS2 Global](https://developer.spreedly.com/docs/spreedly-3ds2-global.md) - [Spreedly 3DS2 Global guide](https://developer.spreedly.com/docs/spreedly-3ds2-global-guide.md) - [Spreedly 3DS2 Global integration guide for web](https://developer.spreedly.com/docs/3ds2-global-integration-guide-web.md) - [Spreedly 3DS2 Global Integration Guide for Mobile Webview](https://developer.spreedly.com/docs/3ds2-global-integration-guide-mobile.md) - [Testing your 3DS2 Global Integration](https://developer.spreedly.com/docs/testing-your-3ds2-global-integration.md) - [Spreedly 3DS2 Global Mobile](https://developer.spreedly.com/docs/3ds-mobile.md): Spreedly mobile SDK support is powered by Forter mobile SDK's. - [Third Party 3DS2 Guide](https://developer.spreedly.com/docs/using-third-party-3ds2-providers.md) - [3DS Global Provider Transition: Seglan to Forter](https://developer.spreedly.com/docs/3ds-global-provider-transition-seglan-to-forter.md): This document serves to outline technical considerations and FAQ's regarding the Spreedly 3DS Global product and it's transition from Seglan to Forter as a technical partner of Spreedly's to produce the solution. - [Spreedly 3DS2 Gateway Specific](https://developer.spreedly.com/docs/3ds2-gateway-specific.md) - [Gateway Specific 3DS2 Guide](https://developer.spreedly.com/docs/gateway-specific-3ds2-guide.md) - [Gateway Specific 3DS2 Integration Guide for Mobile Webview](https://developer.spreedly.com/docs/gateway-specific-3ds2-integration-guide-mobile-webview.md) - [Spreedly 3DS2 gateway specific exemptions](https://developer.spreedly.com/docs/3ds2-gateway-specific-exemptions.md) - [Transaction routing](https://developer.spreedly.com/docs/routing-rules-1.md) - [Recover](https://developer.spreedly.com/docs/recover.md) - [Gateway error code mapping](https://developer.spreedly.com/docs/gateway-error-code-mapping.md) - [Supported Gateways](https://developer.spreedly.com/docs/supported-gateways.md) ## API Reference - [Getting started with Spreedly API](https://developer.spreedly.com/reference/api-introduction.md): This page will help you create and identify API credentials to set up Spreedly's API - [Order and pagination](https://developer.spreedly.com/reference/order-and-pagination.md) - [Response codes](https://developer.spreedly.com/reference/response-codes.md) - [Authorize a payment method token](https://developer.spreedly.com/reference/authorize-1.md): Authorize a payment method to be charged a specific amount at the target gateway. No funds are taken with an authorize – a follow-up [capture](https://docs.spreedly.com/reference/api/v1/#capture) transaction is required to actually move the funds. The referenced gateway must exist in the environment whose environment key is being used to authenticate the API call. **Tokenized payment method:** Authorize a Payment Method Token (already stored in the Spreedly environment) to be charged a specific amount. The `payment_method_token` field of the transaction request is required. **Pass-in credit card:** Pass a credit card payment method directly in to the authorize request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `credit_card` field of the transaction request is required. **Pass-in Apple Pay:** Pass an Apple Pay payment method directly into the authorize request. If the Apple Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `apple_pay` field of the transaction request is required. **Pass-in Google Pay:** Pass a Google Pay payment method directly in to the authorize request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `google_pay` field of the transaction request is required. **SCA Authenticated:** Authorize an SCA Authenticated payment method (already stored in the Spreedly environment) to be charged a specific amount. The `sca_authentication_token` field of the transaction request is required. - [Capture full or partial transaction](https://developer.spreedly.com/reference/capture-transaction.md): Capture funds previously reserved via an authorize. By specifying an amount, you can capture a partial amount. If you omit the amount parameter, the full amount will be captured. - [Card Refresher Inquiry](https://developer.spreedly.com/reference/card_refresher_inquiry.md): Make an inquiry to a card network (currently Visa) to get any applicable updates for the card. - [List certificates](https://developer.spreedly.com/reference/list-certificates.md): Retrieve an [ordered and paginated](https://developer.spreedly.com/reference/order-and-pagination) list of all certificates in the authenticated environment. - [Create a certificate](https://developer.spreedly.com/reference/create-certificates.md): Add a certificate to the authenticated environment for use in [secure payment method tokenization](https://developer.spreedly.com/docs/iframe-api-lifecycle#security-requirements), payment method distribution functions such as [XML digital signatures](https://developer.spreedly.com/reference/order-and-pagination), or to utilize [Apple Pay](https://developer.spreedly.com/docs/apple-pay#generate-certificate). - [Generate a certificate](https://developer.spreedly.com/reference/generate-certificates.md): Generate a new SSL keypair and certificate signing request (CSR). Since Spreedly is not a certificate authority we cannot issue trusted certificates. Instead, it is intended that you will get the certificate signed by your certificate authority (or sign it yourself) and update the certificate record at Spreedly with the final and signed cert. - [Update certificate](https://developer.spreedly.com/reference/update-certificates.md): Update an existing SSL certificate record with the signed certificate value (in PEM format). - [Create an authorization with workflows](https://developer.spreedly.com/reference/composerauthorize.md): Spreedly's workflow service will determine which gateway the transaction will be processed based on the workflow evoked and send normalized fields depending on what the gateway supports. A `workflow_key` should be sent in the request body or left as null to evoke the Default Workflow set in your Spreedly environment. To learn more about how to enable workflows, please contact Spreedly at support@spreedly.com. Pass a credit card payment method directly into the authorize request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. No funds are taken with an authorize - a follow-up capture transaction is required to actually move the funds. **Tokenized payment method:** Charge a _tokenized_ payment method (already stored in the Spreedly environment) the specified amount. The payment method can be of any type (credit card, bank account, Apple Pay, etc…), as long as it exists in the specified environment. The `payment_method_token` field of the transaction request is required. **Pass-in credit card:** Pass a credit card payment method directly in to the authorize request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `credit_card` field of the transaction request is required. **Pass-in Apple Pay:** Pass an Apple Pay payment method directly in to the authorize request. If the Apple Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `apple_pay` field of the transaction request is required. **Pass-in Google Pay:** Pass a Google Pay payment method directly in to the authorize request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `google_pay` field of the transaction request is required. **SCA Authenticated:** Charge an SCA Authenticated payment method (already stored in the Spreedly environment) the specified amount. The `sca_authentication_token` field of the transaction request is required. **Default workflow:** Use the default workflow for the environment that is set in app.spreedly.com The `workflow_key` field is not required to be passed in for this type of request. - [Create a purchase with workflows](https://developer.spreedly.com/reference/composerpurchase.md): Spreedly's workflow service will determine which gateway the transaction will be processed based on the workflow evoked and send normalized fields depending on what the gateway supports. A `workflow_key` should be sent in the request body or left as null to evoke the Default Workflow set in your Spreedly environment. To learn more about how to enable workflows, please contact Spreedly at support@spreedly.com. Charge a payment method a specific amount at the target gateway. One of the following payment methods must be included in the request: **Tokenized payment method:** Charge a _tokenized_ payment method (already stored in the Spreedly environment) the specified amount. The payment method can be of any type (credit card, bank account, Apple Pay, etc…), as long as it exists in the specified environment. The `payment_method_token` field of the transaction request is required. **Pass-in credit card:** Pass a credit card payment method directly in to the purchase request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `credit_card` field of the transaction request is required. **Pass-in Apple Pay:** Pass an Apple Pay payment method directly in to the purchase request. If the Apple Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `apple_pay` field of the transaction request is required. **Pass-in Google Pay:** Pass a Google Pay payment method directly in to the purchase request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `google_pay` field of the transaction request is required. **SCA Authenticated:** Charge an SCA Authenticated payment method (already stored in the Spreedly environment) the specified amount. The `sca_authentication_token` field of the transaction request is required. **Default workflow:** Use the default workflow for the environment that is set in app.spreedly.com The `workflow_key` field is not required to be passed in for this type of request. - [Create a verify with workflows](https://developer.spreedly.com/reference/composerverify.md): Spreedly's workflow service will determine which gateway the transaction will be processed based on the workflow evoked and send normalized fields depending on what the gateway supports. A `workflow_key` should be sent in the request body or left as null to evoke the Default Workflow set in your Spreedly environment. To learn more about how to enable workflows, please contact Spreedly at support@spreedly.com. Determine if a credit card is chargeable card and available for purchases. The `retain_on_success` request parameter will automatically retain the card if it’s successfully verified. **Tokenized payment method:** Charge a _tokenized_ payment method (already stored in the Spreedly environment) the specified amount. The payment method can be of any type (credit card, bank account, Apple Pay, etc…), as long as it exists in the specified environment. The `payment_method_token` field of the transaction request is required. **Pass-in credit card:** Pass a credit card payment method directly in to the verify request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `credit_card` field of the transaction request is required. **SCA Authenticated:** Charge an SCA Authenticated payment method (already stored in the Spreedly environment) the specified amount. The `sca_authentication_token` field of the transaction request is required. **Default workflow:** Use the default workflow for the environment that is set in app.spreedly.com The `workflow_key` field is not required to be passed in for this type of request. - [Create a refund transaction](https://developer.spreedly.com/reference/credit-transaction.md): Refund the full or partial amount of a purchase or capture. [Credit/Refund transactions](https://developer.spreedly.com/docs/create-transactions#payment-orchestration). - [Create a general credit transaction](https://developer.spreedly.com/reference/general-credit-transaction.md): Add funds to a credit card outside the scope of a previous reference transaction. This is different from [credit](https://developer.spreedly.com/reference/credit-transaction) which refunds money only up to the amount that had been taken during a previous transaction. Support for general credit depends on the gateway. - [Regenerate signing secret](https://developer.spreedly.com/reference/regenerate-signing-secret.md): Regenerate environment signing secret. Once this is regenerated, the old signing secret will no longer be valid and you must immediately update your application with the new signing secret. This call should be authenticated with the key of the environment that you are trying to update and an Organization Access Secret. - [List environments](https://developer.spreedly.com/reference/list-environments.md): Retrieve an ordered and paginated list of all environments in an organization. This call should be authenticated with an environment key from the organization and an Organization Access Secret. - [Create an environment](https://developer.spreedly.com/reference/create-environments.md): Create an environment in your organization. You will need to create one environment and access secret manually at app.spreedly.com for authentication. After that you can authenticate the API call using that environment key and an Organization Access Secret. - [Show environment](https://developer.spreedly.com/reference/show-environments.md): Get an environment with the given key. This call should be authenticated with the key of the environment that you are trying to show and an Organization Access Secret. - [Update environment](https://developer.spreedly.com/reference/update-environments.md): Update an existing environment. This call should be authenticated with the key of the environment that you are trying to update and an Organization Access Secret. - [Create environment access secret](https://developer.spreedly.com/reference/create-access-secret.md): Create an access secret in an environment. Authentication should be done using the environment where you want to create the secret and an Organization Access Secret. - [List environment access secrets](https://developer.spreedly.com/reference/list-access-secrets.md): Retrieve a list of all access secrets in an environment. This call should be authenticated with the key of the environment that you are accessing and an Organization Access Secret. - [Show environment access secret](https://developer.spreedly.com/reference/show-access-secrets.md): Get an access secret with the given key. This call should be authenticated with the key of the environment that you are accessing and an Organization Access Secret. - [Delete environment access secret](https://developer.spreedly.com/reference/delete-access-secrets.md): Delete an access secret in an environment. Authentication should be done using the environment where you want to delete the secret and an Organization Access Secret. - [list events](https://developer.spreedly.com/reference/list-events.md): Retrieve an ordered and paginated list of all events in the authenticated environment. - [Show event](https://developer.spreedly.com/reference/show-event.md): Get an event with the given id. - [Create a gateway](https://developer.spreedly.com/reference/create-gateways.md): Create (provision) a gateway to process card data in the authenticated environment. A test gateway is used to [test your integration](https://developer.spreedly.com/docs/testing/) to Spreedly and can only be used with [test payment methods](https://developer.spreedly.com/docs/test-data/). Production gateways process real card data and transactions. Production gateways are created using the credentials required for that gateway, meaning each call is slightly different depending on the gateway's API requirements. - [List created gateways](https://developer.spreedly.com/reference/list-gateways.md): Retrieve an ordered and paginated list of all gateways in the environment. This is different from the list of all supported gateways in that this will only return the gateway instances that have been provisioned in the authenticated environment. - [Show gateway](https://developer.spreedly.com/reference/show-gateways.md): Get a gateway with the given token. - [Update gateway](https://developer.spreedly.com/reference/update-gateway.md): Update a gateway. Update is intended to be used for updating credentials, description, or metadata. - [List supported gateways](https://developer.spreedly.com/reference/list-supported-gateways.md): Retrieve a list of all gateways, and their properties, supported by Spreedly. This call can be used to dynamically present a gateway credential form to users or to do any sort of dynamic rendering. - [Transactions](https://developer.spreedly.com/reference/list-gateway-transactions.md): Get an ordered and paginated list of transactions executed against a specific gateway. - [Redact gateway](https://developer.spreedly.com/reference/redact-gateways.md): Redact (strip of any sensitive credentials and make inactive) a provisioned gateway. - [Retain gateway](https://developer.spreedly.com/reference/retain-gateways.md): When gateways are created via the API, they are automatically retained. However, gateways created via the unauthenticated API (e.g., from a browser/javascript library) are created in the “cached” state. Only by retaining a cached gateway will it be saved and available for future use. - [Create merchant profile](https://developer.spreedly.com/reference/create-merchant-profile.md): Create a Merchant Profile that holds the SCA Provider. **At least one card type object must be included in the request.** The following card types are supported: Visa, Mastercard, American Express, Discover, Diners, JCB, Dankort, Union Pay, and Cartes Bancaires. - [List merchant profiles](https://developer.spreedly.com/reference/list-merchant-profiles.md): Retrieve an [ordered and paginated](https://developer.spreedly.com/reference/order-and-pagination) list of all merchant profiles in the environment - [Show merchant profile](https://developer.spreedly.com/reference/show-merchant-profile.md): Get a merchant profile with the given token. - [Update merchant profile](https://developer.spreedly.com/reference/update-merchant-profile.md): Update the `description` on the Merchant Profile. All other parameters of the Merchant Profile cannot be updated once created. - [Show card metadata for a Network Token](https://developer.spreedly.com/reference/network-tokenization-card-metadata.md): Retrieve metadata for a card that has been tokenized at a network. The content of the `card_metadata` object is determined and can be changed by the card network at any time. Because of this, the keys in the response are potentially variable and should not be considered idempotent. - [Show status for a Network Token](https://developer.spreedly.com/reference/network-tokenization-status.md): Retrieve the status of a card that has been tokenized at a network. This endpoint provides the current status of a network token, either active or inactive. - [payment_methods](https://developer.spreedly.com/reference/payment_methods-1.md): To minimize your PCI assessment burden, please consider using [Spreedly Express](https://developer.spreedly.com/docs/express-payment-form) or the [iFrame payment form](https://developer.spreedly.com/docs/iframe-payment-form) to send payment information to Spreedly. Using the API directly requires that the card data pass through your system which increases your PCI scope. - [Create payment method](https://developer.spreedly.com/reference/create-payment-method.md): Add a payment method (credit card, bank account/ACH, Apple Pay, Google Pay, or third party token) to the authenticated environment's vault. To create a test payment method, use one of the [test card numbers](https://developer.spreedly.com/docs/test-data). For more information see the [Spreedly testing guide](https://developer.spreedly.com/docs/testing). Third party tokens are payment methods stored in the Spreedly vault, that are a reference to another payment method stored at the gateway's vault. For more information see the [third party token guide](https://developer.spreedly.com/docs/third-party-vaulting). - [Field-level encryption](https://developer.spreedly.com/reference/field-level-encryption.md) - [List payment methods](https://developer.spreedly.com/reference/list-payment-method.md): Retrieve an ordered and paginated list of all retained payment methods in the authenticated environment. *States* Payment methods can exist in several states in the Spreedly vault - retained, redacted, cached, used, or closed. Retained payment methods are stored in Spreedly's vault until redacted. Redacted payment methods are payment methods that were either not retained or have been manually redacted. Cached payment methods are payment methods that have not been retained but have not yet been automatically redacted yet. Cached payment methods can still be retained. For more information, please see our guide on [retaining payment methods](https://developer.spreedly.com/docs/create-transactions#retain). If no state parameter or an invalid state parameter is passed, list will only return retained payment methods. If the state parameter is passed, list will return those parameters: retained, redacted, cached. Example: `https://core.spreedly.com/v1/payment_methods.json?state=retained,redacted,cached` If the state parameter is combined with other existing parameters such as metadata, both will be considered. Example: `https://core.spreedly.com/v1/payment_methods.json?metadata[customer_id]=123abc&state=redacted,retained` - [Show payment method](https://developer.spreedly.com/reference/show-payment-method.md): Get a payment method with the given token. - [Update payment method](https://developer.spreedly.com/reference/update-payment-method.md): Update a payment method's non-sensitive attributes. - [Retain payment method](https://developer.spreedly.com/reference/retain-payment-method.md): Retain (keep in the Spreedly vault for future use) a payment method. - [Redact payment method](https://developer.spreedly.com/reference/redact-payment-method.md): Redact (strip of any sensitive credentials and make inactive) a payment method. - [Update management payment method](https://developer.spreedly.com/reference/update-gratis-payment-method.md): Update a payment method's management state. For further details, see [Advanced Vault](https://developer.spreedly.com/docs/advanced-vault). Please note, that this API call is only available to merchants who are currently enrolled in Advanced Vault. - [List transactions payment method](https://developer.spreedly.com/reference/list-transactions-payment-method.md): Get an ordered and paginated list of transactions executed against a specific payment method. - [Delete metadata payment method](https://developer.spreedly.com/reference/delete-metadata-payment-method.md): Remove key value pairs from a payment method's metadata. - [Recache payment method](https://developer.spreedly.com/reference/recache-payment-method.md): Update a credit card's verification value (CVV) so the card can be transacted against. Note: A credit card must be retained in your environment in order to re-cache its CVV. - [Create a store transaction](https://developer.spreedly.com/reference/payment_methodstore.md): Tokenize a payment method *at the gateway*. This transaction copies the payment method information from the Spreedly vault [to the gateway's vault](https://developer.spreedly.com/docs/third-party-vaulting) and creates a new Spreedly payment method to represent the gateway's version. The reference to the payment method at the gateway is called a ThirdPartyToken and is a separate payment method from the original payment method. It is up to you to manage the lifecycle of these linked payment methods – Spreedly does not keep them in sync in any way. The ThirdPartyToken is locked to the gateway where the card is stored; it cannot be used at another gateway. If you'd like a card to be used at multiple gateways, you'll need to [retain the card in the Spreedly vault](https://developer.spreedly.com/docs/create-transactions#retain). - [Forward a claim to the protection provider](https://developer.spreedly.com/reference/forward-claim.md): Forward a claim to the protection provider - [Create a protection provider on the given merchant profile](https://developer.spreedly.com/reference/create-protection-provider.md): Create a Protection Provider on the given Merchant Profile. A Protection Provider can be used as part of [authorize](https://developer.spreedly.com/reference/authorize), [purchase](https://developer.spreedly.com/reference/purchase), and [verify](https://developer.spreedly.com/reference/verify) transactions. **At least one card type object must be included in the request.** The following card types are supported: `Visa`, `Mastercard`, `American Express`, `Discover`, `Diners`, `JCB`, `Dankort`, `Union Pay`, and `Cartes Bancaires`. - [Show protection provider](https://developer.spreedly.com/reference/show-protection-provider.md): Get a Protection Provider with the given token. A Protection Provider can be used as part of [authorize](https://developer.spreedly.com/reference/authorize), [purchase](https://developer.spreedly.com/reference/purchase), and [verify](https://developer.spreedly.com/reference/verify) transactions. - [Create a purchase transaction](https://developer.spreedly.com/reference/purchase.md): Charge a payment method a specific amount at the target gateway. One of the following payment methods must be included in the request: **Tokenized payment method:** Charge a _tokenized_ payment method (already stored in the Spreedly environment) the specified amount. The payment method can be of any type (credit card, bank account, Apple Pay, etc…), as long as it exists in the specified environment. The `payment_method_token` field of the transaction request is required. **Pass-in credit card:** Pass a credit card payment method directly in to the purchase request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `credit_card` field of the transaction request is required. **Pass-in bank account/ACH:** Pass a bank account/ACH payment method directly in to the purchase request. If the bank account is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `bank_account` field of the transaction request is required. **Pass-in Apple Pay:** Pass an Apple Pay payment method directly in to the purchase request. If the Apple Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `apple_pay` field of the transaction request is required. **Pass-in Google Pay:** Pass a Google Pay payment method directly in to the purchase request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `google_pay` field of the transaction request is required. **SCA Authenticated:** Charge an SCA Authenticated payment method (already stored in the Spreedly environment) the specified amount. The `sca_authentication_token` field of the transaction request is required. - [Create a purchase transaction via reference](https://developer.spreedly.com/reference/reference-purchase.md): Execute a purchase using the payment method [utilized in a previous transaction](https://developer.spreedly.com/docs/using-payment-methods#reference-purchases). The `currency_code` field is optional for this type of purchase request. It can be inferred from the referenced transaction. - [List supported receivers](https://developer.spreedly.com/reference/list-supported-receivers.md): Retrieve a list of all payment method distribution receivers, and their properties, supported by Spreedly. Note that this request is publicly available and _does not require authorization_. - [Create a receiver](https://developer.spreedly.com/reference/create-receiver.md): Create a receiver for use in [payment method distribution](https://developer.spreedly.com/docs/payment-method-distribution) - [List created receivers](https://developer.spreedly.com/reference/list-created-receivers.md): Retrieve an [ordered and paginated](https://developer.spreedly.com/reference/order-and-pagination) list of all receivers in the authenticated environment. - [Show a receiver](https://developer.spreedly.com/reference/show-receiver.md): Get a receiver with the given token - [Update a receiver](https://developer.spreedly.com/reference/update-receiver.md): Update a receiver with new credentials - [Redact a receiver](https://developer.spreedly.com/reference/redact-receiver.md): Redact (strip of any sensitive credentials and make inactive) a receiver. - [Deliver payment method](https://developer.spreedly.com/reference/deliver-payment-method.md): Deliver a payment method to the specified receiver endpoint. See the guide on [payment method distribution](https://developer.spreedly.com/docs/payment-method-distribution) to understand how to specify what is sent to the receiver. Spreedly provides an open [repository of code templates](https://github.com/spreedly/templates) for simplifying implementation of new receivers. - [Export payment methods](https://developer.spreedly.com/reference/export-payment-methods.md): Export multiple payment methods in a single, asynchronous, batch call to an SFTP receiver endpoint. - [sca_authentication](https://developer.spreedly.com/reference/sca_authentication.md): An SCA Authentication is a Spreedly transaction type that allows you to authenticate a payment method and amount prior to `purchase` and `authorize` transactions. Spreedly exposes SCA Authentications in the following ways: 1. SCA Authentication endpoint to perform an SCA Authentication on payment methods in order to be compliant with SCA enforcement. 2. SCA Authentications can be performed as part of Spreedly Global 3DS transactions, `purchase and authorize` - [Authenticate a given payment method](https://developer.spreedly.com/reference/authenticate.md): Authenticate a given payment method and amount against provided SCA Provider Key (specified in the request URL) Notable response elements can be found in the table below. All other response elements are used by our `Spreedly.ThreeDS.Lifecycle` helpers and exposed for debugging purposes. We recommend that our merchants not use any fields that are not listed in the table below. - [Show transaction](https://developer.spreedly.com/reference/show-transactions.md): Get the transaction with the given token. Any interaction that creates or updates information via the Spreedly API, or sends information to a third party such as a gateway or receiver, will generate a corresponding transaction record that may be viewed by submitting its `transaction_token`. This may be viewable in the body of the original response or by retrieving it from the Transactions List in the [Spreedly app](https//app.spreedly.com). - [Update transaction](https://developer.spreedly.com/reference/update-transactions.md): Run an inquiry for a transaction's status at the gateway and update the state of the Spreedly transaction with the given token. Only for supported gateways. See our [syncing transactions guide](https://developer.spreedly.com/docs/syncing-your-gateway-transaction) for more information. - [Complete transaction](https://developer.spreedly.com/reference/complete-transactions.md): Attempts to complete or advance a pending 3DS 2 transaction. We require merchants to make authenticated calls to this endpoint in response to certain `Spreedly.ThreeDS.Lifecycle` events being emitted: A pending transaction with a `required_action` of `device_fingerprint` will fire a `trigger-completion` event when the transaction status was updated due to a callback in the cardholder's iFrame or when 10 seconds have elapsed. When this event is received, it is necessary to call `complete` so that the latest transaction state can be retrieved in case of a timeout. A pending transaction with a `required_action` of `challenge` will fire a `finalization-timeout` when our `Spreedly.ThreeDS.Lifecycle` stops polling for updates after 10-15 minutes of not receiving a new status. When this event is received, it is recommended that merchants call `complete` so that the transaction state can be updated due to cardholder abandonment or missed callbacks. Please see our [3DS2 guides](https://developer.spreedly.com/docs/3ds-solutions) for more information and reference implementations. - [List transactions](https://developer.spreedly.com/reference/list-transactions.md): Retrieve an [ordered and paginated](https://docs.spreedly.com/reference/api/v1/#order-and-pagination) list of all transactions in the authenticated environment. This endpoint is [rate-limited](https://docs.spreedly.com/reference/api/v1/#429-too-many-requests) to 30 requests per minute, per environment. - [Confirm transaction](https://developer.spreedly.com/reference/confirm-transactions.md): Attempts to confirm a pending offsite purchase, offsite synchronous purchase or offsite synchronous authorization. **Braintree** A `processing` transaction with a `payment_method_type` of 'paypal' or 'venmo' is needed to confirm this transaction. [A object returned in iFrame](https://developer.spreedly.com/docs/braintree-gateway-guide#example-responses-for-callbackfunction). This could contain the following parameters; `state`, `nonce`, `payment_method`, `device_date`, `username` Please see our [Braintree APM section](https://developer.spreedly.com/docs/braintree-gateway-guide#alternative-payment-methods) for more information and reference implementations. **Stripe** For Stripe this offsite purchase is using APMs with a card payment. A pending transaction with a `payment_method` of type 'stripe_apm' is needed to confirm this transaction. A `payment_method_token` or credit card details in a `payment_method` object must be passed. Please see our [Stripe APM guide](https://developer.spreedly.com/docs/stripe-apm-offsite-payments) for more information and reference implementations. BIN metadata is available in the response if the card is enrolled in Advanced Vault. See [BIN metadata](https://developer.spreedly.com/docs/bin-metadata) for more information. - [Transaction transcript](https://developer.spreedly.com/reference/transcript-transactions.md): View the exchange between Spreedly and the external service (gateway, receiver, etc…) for the given transaction in a human-readable, text format. The transcript is scrubbed of sensitive information so you can email it to external support representatives to help in debugging and other support tasks. As of December 31, 2022, Spreedly retains transaction transcripts for 90 days after the initial date of the transaction. Transcript requests for transactions which are older than 90 days will return a 404 http response. A transcript is not meant to be machine parseable and, as such, its format may change at any time without warning. - [Create an sca provider on the given merchant profile](https://developer.spreedly.com/reference/create-sca-provider.md): Create an SCA Provider on the given Merchant Profile. An SCA Provider can be used to run [3DS2 Global](https://developer.spreedly.com/docs/3ds-solutions) authentications on the [authenticate](https://developer.spreedly.com/reference/authenticate) endpoint or as part of [authorize](https://developer.spreedly.com/reference/authorize) and [purchase](https://developer.spreedly.com/reference/purchase) transactions. At least one card type object must be included in the request. The following card types are supported: `Visa`, `Mastercard`, `American Express`, and `Discover`. - [Show sca provider](https://developer.spreedly.com/reference/show-sca-provider.md): Get an SCA Provider with the given token. An SCA Provider can be used to run [3DS2 Global](https://developer.spreedly.com/docs/3ds-solutions) authentications on the [authenticate](https://docs.spreedly.com/reference/api/v1/#authenticate) endpoint or as part of [authorize](https://docs.spreedly.com/reference/api/v1/#authorize) and [purchase](https://docs.spreedly.com/reference/api/v1/#purchase) transactions. - [List sub_merchants](https://developer.spreedly.com/reference/list-sub-merchant.md): Retrieve an ordered and paginated list of all Sub-merchants in an organization. This call should be authenticated with an environment key from the organization and an Organization Access Secret. - [Create sub_merchant](https://developer.spreedly.com/reference/create-sub-merchant.md): Create a sub-merchant - [Show sub_merchant](https://developer.spreedly.com/reference/show-sub-merchant.md): Get the sub-merchant with the given key. - [Update sub_merchant](https://developer.spreedly.com/reference/ubdate-sub-merchant.md): Update a sub-merchant - [Verify a payment method](https://developer.spreedly.com/reference/verify-payment-method.md): Determine if a credit card is a [chargeable card and available for purchases](https://developer.spreedly.com/docs/using-payment-methods#verifying-a-card). The `retain_on_success` request parameter will automatically retain the card if it’s successfully verified. Also used by Ebanx Gateway customers as part of the enrollment process for Mercado Pago recurring payments. To learn more about this visit [Ebanx Gateway](https://developer.spreedly.com/docs/ebanx-gateway-guide). - [Void a transaction](https://developer.spreedly.com/reference/void-transaction.md): Cancel an `authorization` transaction or a `capture`/`purchase` transaction that hasn’t yet settled at the merchant account. This API call can also be used to cancel a `verify` transaction that was part of the Ebanx customer enrollment process. To learn more about this visit [Ebanx Gateway](https://developer.spreedly.com/docs/ebanx-gateway-guide). ## Changelog - [New Spreedly Protect Reporting](https://developer.spreedly.com/changelog/new-spreedly-protect-reporting.md) - [Update network transaction ID handling on IPG gateway](https://developer.spreedly.com/changelog/update-network-transaction-id-handling-on-ipg-gateway.md) - [Support Apple Pay on dLocal gateway](https://developer.spreedly.com/changelog/support-apple-pay-on-dlocal-gateway.md) - [Developer documentation restructured by product area](https://developer.spreedly.com/changelog/developer-documentation-restructured-by-product-area.md) - [Support gateway specific response field on the Airwallex gateway](https://developer.spreedly.com/changelog/support-gateway-specific-response-field-on-the-airwallex-gateway.md)