Introduction
These are the API docs for version 1 of the Spreedly API (previously Spreedly Core).
API v1 is a standard REST-style API that accepts/returns XML or JSON requests and is located at:
https://core.spreedly.com/v1/
API examples
These API reference docs are meant to clearly define the URLs, parameters, request bodies, responses and error states of the Spreedly API. Most sections will be accompanied by the HTTP representation of the API call in the right-most column and should be easily translated to the equivalent curl (or other library) command.
For instance, the following HTTP request representation:
Is equivalent to the following curl command:
The response section immediately follows the request and outputs both the HTTP response code:
as well as the response body itself:
Variables
POST /v1/gateways/<gateway_token>/verify.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"retain_on_success": true
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<retain_on_success>true</retain_on_success>
</transaction>
Request variables are displayed as <var_name> with the docs. Anytime a variable exists in an example API request, it will be defined in the associated request/response element tables.
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Unless a variable is denoted as required, it is optional and can be omitted.
Using the API
Authentication
Unless otherwise noted, all calls to the Spreedly API use HTTP basic authentication over HTTPS. Spreedly requires TLS 1.2.
Use the environment key of the Spreedly environment you wish to execute against as the HTTP basic user, and one of your organization’s access secrets as the HTTP basic password.
HTTP basic authentication can be set when using curl in the -u option as environment-key:access-secret.
$ curl https://core.spreedly.com/v1/gateways.json -u 'env_key:secret'
JSON endpoints
To make a request for the JSON version of an endpoint, send the Content-Type: application/json header to the endpoint with the .json URL suffix.
JSON endpoint examples are contained within the json tab of the code column here in the docs. If some part of the documentation is ambiguous to the format, it will be displayed in all code tabs.
XML endpoints
To make a request for the XML version of an endpoint, send the Content-Type: application/xml header to the endpoint with the .xml URL suffix.
XML endpoint examples are contained within the xml tab of the code column here in the docs. If some part of the documentation is ambiguous to the format, it will be displayed in all code tabs.
Gateways
List supported gateways
GET /v1/gateways_options.<format> HTTPS/1.1
Host: core.spreedly.com
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"gateways": [
{
"gateway_type": "acapture",
"name": "Acapture",
"auth_modes": [
{
"auth_mode_type": "default",
"name": "Default",
"credentials": [
{
"name": "entity_id",
"label": "Entity Id",
"safe": true
},
{
"name": "access_token",
"label": "Access Token",
"safe": false
}
]
}
],
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"void",
"verify"
],
"payment_methods": [
"credit_card"
],
"gateway_settings": [
],
"gateway_specific_fields": [
"disable_3d_secure"
],
"supported_countries": [
"AD",
"AI",
"AT",
"BE",
"BG",
"CA",
"HR",
"CY",
"CZ",
"DK",
"EE",
"FI",
"FR",
"DE",
"GR",
"HK",
"HU",
"IS",
"IT",
"LV",
"LI",
"LT",
"LU",
"MT",
"MC",
"NL",
"PL",
"PT",
"SM",
"SK",
"SI",
"ES",
"SE",
"CH",
"TR",
"GB",
"US"
],
"supported_cardtypes": [
"visa",
"master",
"american_express",
"diners_club",
"discover",
"jcb",
"maestro",
"dankort"
],
"regions": [
"asia_pacific",
"europe",
"north_america"
],
"homepage": "https://www.acapture.com",
"display_api_url": "https://oppwa.com/v1/payments",
"company_name": "Acapture"
},
{
"gateway_type": "adyen",
"name": "Adyen",
"auth_modes": [
{
"auth_mode_type": "default",
"name": "Default",
"credentials": [
{
"name": "merchant_account",
"label": "Merchant Account",
"safe": true
},
{
"name": "username",
"label": "Username",
"safe": true
},
{
"name": "password",
"label": "Password",
"safe": false
}
]
}
],
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials",
"card_scheme_ntid",
"moto_exemption",
"low_value_exemption"
],
"payment_methods": [
"credit_card",
"apple_pay",
"google_pay",
"third_party_token",
"bank_account"
],
"gateway_settings": [
{
"name": "subdomain",
"label": "Subdomain"
}
],
"gateway_specific_fields": [
"shopper_reference",
"shopper_statement",
"fraud_offset",
"selected_brand",
"delivery_date",
"merchant_order_reference",
"shopper_interaction",
"installments",
"recurring_processing_model",
"brand_override",
"custom_routing_flag",
"user_agent",
"accept_header",
"risk_data",
"shopper_ip",
"threed_dynamic",
"idempotency_key",
"device_fingerprint",
"adjust_authorisation_data",
"authorisation_type",
"requested_test_acquirer_response_code",
"update_shopper_statement",
"industry_usage",
"capture_delay_hours",
"splits",
"tokenize_only",
"recurring_contract_type",
"recurring_detail_reference",
"sub_merchant_id",
"sub_merchant_name",
"sub_merchant_street",
"sub_merchant_city",
"sub_merchant_state",
"sub_merchant_postal_code",
"sub_merchant_country",
"sub_merchant_tax_id",
"sub_merchant_mcc",
"sub_merchant_data",
"cancel_or_refund",
"network_transaction_id",
"external_platform",
"merchant_application",
"verify_amount",
"level_2_data",
"level_3_data",
"additional_data_airline",
"additional_data_lodging",
"store",
"date_of_birth",
"nationality",
"fund_source",
"address_override",
"mcc",
"metadata"
],
"supported_countries": [
"AT",
"AU",
"BE",
"BG",
"BR",
"CH",
"CY",
"CZ",
"DE",
"DK",
"EE",
"ES",
"FI",
"FR",
"GB",
"GI",
"GR",
"HK",
"HU",
"IE",
"IS",
"IT",
"LI",
"LT",
"LU",
"LV",
"MC",
"MT",
"MX",
"NL",
"NO",
"PL",
"PT",
"RO",
"SE",
"SG",
"SK",
"SI",
"US"
],
"supported_cardtypes": [
"visa",
"master",
"american_express",
"diners_club",
"jcb",
"dankort",
"maestro",
"discover",
"elo",
"naranja",
"cabal",
"unionpay"
],
"regions": [
"asia_pacific",
"europe",
"latin_america",
"north_america"
],
"homepage": "https://www.adyen.com/",
"display_api_url": "https://pal-live.adyen.com/pal/servlet/",
"company_name": "Adyen"
}
]
}
<gateways>
<gateway>
<gateway_type>acapture</gateway_type>
<name>Acapture</name>
<auth_modes>
<auth_mode>
<auth_mode_type>default</auth_mode_type>
<name>Default</name>
<credentials>
<credential>
<name>entity_id</name>
<label>Entity Id</label>
<safe type="boolean">true</safe>
</credential>
<credential>
<name>access_token</name>
<label>Access Token</label>
<safe type="boolean">false</safe>
</credential>
</credentials>
</auth_mode>
</auth_modes>
<gateway_settings>
</gateway_settings>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">false</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">false</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">false</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
</characteristics>
<payment_methods>
<payment_method>credit_card</payment_method>
</payment_methods>
<gateway_specific_fields>
<gateway_specific_field>disable_3d_secure</gateway_specific_field>
</gateway_specific_fields>
<supported_countries>AD, AI, AT, BE, BG, CA, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HK, HU, IS, IT, LV, LI, LT, LU, MT, MC, NL, PL, PT, SM, SK, SI, ES, SE, CH, TR, GB, US</supported_countries>
<supported_cardtypes>visa, master, american_express, diners_club, discover, jcb, maestro, dankort</supported_cardtypes>
<regions>asia_pacific, europe, north_america</regions>
<homepage>https://www.acapture.com</homepage>
<display_api_url>https://oppwa.com/v1/payments</display_api_url>
<company_name>Acapture</company_name>
</gateway>
<gateway>
<gateway_type>adyen</gateway_type>
<name>Adyen</name>
<auth_modes>
<auth_mode>
<auth_mode_type>default</auth_mode_type>
<name>Default</name>
<credentials>
<credential>
<name>merchant_account</name>
<label>Merchant Account</label>
<safe type="boolean">true</safe>
</credential>
<credential>
<name>username</name>
<label>Username</label>
<safe type="boolean">true</safe>
</credential>
<credential>
<name>password</name>
<label>Password</label>
<safe type="boolean">false</safe>
</credential>
</credentials>
</auth_mode>
</auth_modes>
<gateway_settings>
<gateway_setting>
<name>subdomain</name>
<label>Subdomain</label>
</gateway_setting>
</gateway_settings>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
<supports_card_scheme_ntid type="boolean">true</supports_card_scheme_ntid>
<supports_moto_exemption type="boolean">true</supports_moto_exemption>
<supports_low_value_exemption type="boolean">true</supports_low_value_exemption>
</characteristics>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
</payment_methods>
<gateway_specific_fields>
<gateway_specific_field>shopper_reference</gateway_specific_field>
<gateway_specific_field>shopper_statement</gateway_specific_field>
<gateway_specific_field>fraud_offset</gateway_specific_field>
<gateway_specific_field>selected_brand</gateway_specific_field>
<gateway_specific_field>delivery_date</gateway_specific_field>
<gateway_specific_field>merchant_order_reference</gateway_specific_field>
<gateway_specific_field>shopper_interaction</gateway_specific_field>
<gateway_specific_field>installments</gateway_specific_field>
<gateway_specific_field>recurring_processing_model</gateway_specific_field>
<gateway_specific_field>brand_override</gateway_specific_field>
<gateway_specific_field>custom_routing_flag</gateway_specific_field>
<gateway_specific_field>user_agent</gateway_specific_field>
<gateway_specific_field>accept_header</gateway_specific_field>
<gateway_specific_field>risk_data</gateway_specific_field>
<gateway_specific_field>shopper_ip</gateway_specific_field>
<gateway_specific_field>threed_dynamic</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>device_fingerprint</gateway_specific_field>
<gateway_specific_field>adjust_authorisation_data</gateway_specific_field>
<gateway_specific_field>authorisation_type</gateway_specific_field>
<gateway_specific_field>requested_test_acquirer_response_code</gateway_specific_field>
<gateway_specific_field>update_shopper_statement</gateway_specific_field>
<gateway_specific_field>industry_usage</gateway_specific_field>
<gateway_specific_field>capture_delay_hours</gateway_specific_field>
<gateway_specific_field>splits</gateway_specific_field>
<gateway_specific_field>tokenize_only</gateway_specific_field>
<gateway_specific_field>recurring_contract_type</gateway_specific_field>
<gateway_specific_field>recurring_detail_reference</gateway_specific_field>
<gateway_specific_field>sub_merchant_id</gateway_specific_field>
<gateway_specific_field>sub_merchant_name</gateway_specific_field>
<gateway_specific_field>sub_merchant_street</gateway_specific_field>
<gateway_specific_field>sub_merchant_city</gateway_specific_field>
<gateway_specific_field>sub_merchant_state</gateway_specific_field>
<gateway_specific_field>sub_merchant_postal_code</gateway_specific_field>
<gateway_specific_field>sub_merchant_country</gateway_specific_field>
<gateway_specific_field>sub_merchant_tax_id</gateway_specific_field>
<gateway_specific_field>sub_merchant_mcc</gateway_specific_field>
<gateway_specific_field>sub_merchant_data</gateway_specific_field>
<gateway_specific_field>cancel_or_refund</gateway_specific_field>
<gateway_specific_field>network_transaction_id</gateway_specific_field>
<gateway_specific_field>external_platform</gateway_specific_field>
<gateway_specific_field>merchant_application</gateway_specific_field>
<gateway_specific_field>verify_amount</gateway_specific_field>
<gateway_specific_field>level_2_data</gateway_specific_field>
<gateway_specific_field>level_3_data</gateway_specific_field>
<gateway_specific_field>additional_data_airline</gateway_specific_field>
<gateway_specific_field>additional_data_lodging</gateway_specific_field>
<gateway_specific_field>store</gateway_specific_field>
<gateway_specific_field>date_of_birth</gateway_specific_field>
<gateway_specific_field>nationality</gateway_specific_field>
<gateway_specific_field>fund_source</gateway_specific_field>
<gateway_specific_field>address_override</gateway_specific_field>
<gateway_specific_field>mcc</gateway_specific_field>
<gateway_specific_field>metadata</gateway_specific_field>
</gateway_specific_fields>
<supported_countries>AT, AU, BE, BG, BR, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GI, GR, HK, HU, IE, IS, IT, LI, LT, LU, LV, MC, MT, MX, NL, NO, PL, PT, RO, SE, SG, SK, SI, US</supported_countries>
<supported_cardtypes>visa, master, american_express, diners_club, jcb, dankort, maestro, discover, elo, naranja, cabal, unionpay</supported_cardtypes>
<regions>asia_pacific, europe, latin_america, north_america</regions>
<homepage>https://www.adyen.com/</homepage>
<display_api_url>https://pal-live.adyen.com/pal/servlet/</display_api_url>
<company_name>Adyen</company_name>
</gateway>
</gateways>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateways | Root element |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway. |
| ❯ auth_modes | A list of authorization modes for the gateway. An auth mode is basically a list of credentials required for this gateway (some gateways support various ways of entering credentials). |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
| ❯ supported_countries | The list of countries this gateway supports |
| ❯ supported_cardtypes | The list of credit card brands this gateway supports |
| ❯ regions | The list of geographic regions this gateway supports (determined by the supported_countries) |
List created gateways
GET /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"gateways": [
{
"token": "CtehwikoMnllHsr3XFfAY1EzPkN",
"gateway_type": "test",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"google_pay"
],
"state": "retained",
"created_at": "2017-06-22T13:19:11Z",
"updated_at": "2017-11-27T21:08:11Z",
"name": "Spreedly Test",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"offsite_synchronous_purchase",
"offsite_synchronous_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials"
],
"credentials": [
],
"gateway_settings": {
},
"gateway_specific_fields": [
"simulate_error",
"simulate_decline",
"idempotency_key",
"mit_override_demo"
],
"redacted": false,
"sandbox": false,
"mode": "default"
},
{
"token": "7NTzuQfnaNU2Jr4cVgOt7jfTVGq",
"gateway_type": "test",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"google_pay"
],
"state": "retained",
"created_at": "2017-06-22T14:16:23Z",
"updated_at": "2017-11-27T21:44:49Z",
"name": "Spreedly Test",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"offsite_synchronous_purchase",
"offsite_synchronous_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials"
],
"credentials": [
],
"gateway_settings": {
},
"gateway_specific_fields": [
"simulate_error",
"simulate_decline",
"idempotency_key",
"mit_override_demo"
],
"redacted": false,
"sandbox": false,
"mode": "default"
}
]
}
<gateways>
<gateway>
<token>CtehwikoMnllHsr3XFfAY1EzPkN</token>
<gateway_type>test</gateway_type>
<name>Spreedly Test</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_reference_authorization type="boolean">true</supports_reference_authorization>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>simulate_error</gateway_specific_field>
<gateway_specific_field>simulate_decline</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>mit_override_demo</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>sprel</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2017-06-22T13:19:11Z</created_at>
<updated_at type="dateTime">2017-11-27T21:08:11Z</updated_at>
</gateway>
<gateway>
<token>7NTzuQfnaNU2Jr4cVgOt7jfTVGq</token>
<gateway_type>test</gateway_type>
<name>Spreedly Test</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_reference_authorization type="boolean">true</supports_reference_authorization>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>simulate_error</gateway_specific_field>
<gateway_specific_field>simulate_decline</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>mit_override_demo</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>sprel</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2017-06-22T14:16:23Z</created_at>
<updated_at type="dateTime">2017-11-27T21:44:49Z</updated_at>
</gateway>
</gateways>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
| count | The number of gateways to return. By default returns 20, maximum allowed is 100. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateways | Root element |
| ❯ token | The token identifying the provisioned gateway at Spreedly |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway |
| ❯ description | The description of the provisioned gateway |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the provisioned gateway |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the provisioned gateway |
| ❯ state | The storage state of the gateway (retained, redacted, etc…) |
| ❯ sandbox | If the gateway was created in sandbox mode or not |
| ❯ redacted | If this gateway is redacted or not |
| ❯ credentials | The non-sensitive credentials used for this gateway |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
Create test gateway
POST /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "test"
}
}
<gateway>
<gateway_type>test</gateway_type>
</gateway>
HTTPS/1.1 201 Created
{
"gateway": {
"token": "HaQOnzrDfDHdqWmO0WAjw9zDjGE",
"gateway_type": "test",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"google_pay"
],
"state": "retained",
"created_at": "2023-06-06T17:15:23Z",
"updated_at": "2023-06-06T17:15:23Z",
"name": "Spreedly Test",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"offsite_synchronous_purchase",
"offsite_synchronous_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials"
],
"credentials": [
],
"gateway_settings": {
},
"gateway_specific_fields": [
"simulate_error",
"simulate_decline",
"idempotency_key",
"mit_override_demo"
],
"redacted": false,
"sandbox": false,
"mode": "default"
}
}
<gateway>
<token>7dPJgE2MQZajMypeVkpfWnNMRlk</token>
<gateway_type>test</gateway_type>
<name>Spreedly Test</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_reference_authorization type="boolean">true</supports_reference_authorization>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>simulate_error</gateway_specific_field>
<gateway_specific_field>simulate_decline</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>mit_override_demo</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>sprel</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2023-06-06T17:16:02Z</created_at>
<updated_at type="dateTime">2023-06-06T17:16:02Z</updated_at>
</gateway>
Create (provision) a test gateway in the authenticated environment. A test gateway is used to test your integration to Spreedly and can only be used with test payment methods.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ gateway_type required |
The type of gateway, e.g., test for a test gateway. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ token | The token identifying the provisioned gateway at Spreedly |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway |
| ❯ description | The description of the provisioned gateway |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the provisioned gateway |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the provisioned gateway |
| ❯ state | The storage state of the gateway (retained, redacted, etc…) |
| ❯ sandbox | If the gateway was created in sandbox mode or not |
| ❯ redacted | If this gateway is redacted or not |
| ❯ credentials | The non-sensitive credentials used for this gateway |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
Create sandbox gateway
POST /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "stripe",
"login": "your Stripe API secret",
"sandbox": true
}
}
<gateway>
<gateway_type>stripe</gateway_type>
<login>your api secret key</login>
<sandbox>true</sandbox>
</gateway>
HTTPS/1.1 201 Created
{
"gateway": {
"token": "UlSR3GCgSBzryKio8zeIF4aIHqm",
"gateway_type": "stripe",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"third_party_token",
"apple_pay",
"bank_account",
"google_pay"
],
"state": "retained",
"created_at": "2022-06-22T20:15:29Z",
"updated_at": "2022-06-22T20:15:29Z",
"name": "Stripe",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"void",
"verify",
"3dsecure_purchase",
"3dsecure_authorize",
"store",
"remove"
],
"credentials": [
],
"gateway_settings": {
"webhook_id": null,
"version_override": null
},
"gateway_specific_fields": [
"receipt_email",
"radar_session_id",
"skip_radar_rules",
"application_fee",
"stripe_account",
"metadata",
"idempotency_key",
"reason",
"refund_application_fee",
"refund_fee_amount",
"reverse_transfer",
"account_id",
"customer_id",
"validate",
"make_default",
"statement_description",
"statement_descriptor_suffix",
"destination",
"destination_amount",
"merchant_reference",
"customer_reference",
"shipping_address_zip",
"shipping_from_zip",
"shipping_amount",
"line_items",
"transfer_destination",
"transfer_amount",
"transfer_group",
"on_behalf_of",
"application_fee_amount",
"recurring"
],
"redacted": false,
"sandbox": true,
"mode": "default"
}
}
<gateway>
<token>XalHWUjzXpdSfHUTGUYtFvtEbll</token>
<gateway_type>stripe</gateway_type>
<name>Stripe</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">false</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
<webhook_id nil="true"></webhook_id>
<version_override nil="true"></version_override>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>receipt_email</gateway_specific_field>
<gateway_specific_field>radar_session_id</gateway_specific_field>
<gateway_specific_field>skip_radar_rules</gateway_specific_field>
<gateway_specific_field>application_fee</gateway_specific_field>
<gateway_specific_field>stripe_account</gateway_specific_field>
<gateway_specific_field>metadata</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>reason</gateway_specific_field>
<gateway_specific_field>refund_application_fee</gateway_specific_field>
<gateway_specific_field>refund_fee_amount</gateway_specific_field>
<gateway_specific_field>reverse_transfer</gateway_specific_field>
<gateway_specific_field>account_id</gateway_specific_field>
<gateway_specific_field>customer_id</gateway_specific_field>
<gateway_specific_field>validate</gateway_specific_field>
<gateway_specific_field>make_default</gateway_specific_field>
<gateway_specific_field>statement_description</gateway_specific_field>
<gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
<gateway_specific_field>destination</gateway_specific_field>
<gateway_specific_field>destination_amount</gateway_specific_field>
<gateway_specific_field>merchant_reference</gateway_specific_field>
<gateway_specific_field>customer_reference</gateway_specific_field>
<gateway_specific_field>shipping_address_zip</gateway_specific_field>
<gateway_specific_field>shipping_from_zip</gateway_specific_field>
<gateway_specific_field>shipping_amount</gateway_specific_field>
<gateway_specific_field>line_items</gateway_specific_field>
<gateway_specific_field>transfer_destination</gateway_specific_field>
<gateway_specific_field>transfer_amount</gateway_specific_field>
<gateway_specific_field>transfer_group</gateway_specific_field>
<gateway_specific_field>on_behalf_of</gateway_specific_field>
<gateway_specific_field>application_fee_amount</gateway_specific_field>
<gateway_specific_field>recurring</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">true</sandbox>
<mode>default</mode>
<created_at type="dateTime">2022-06-22T20:15:27Z</created_at>
<updated_at type="dateTime">2022-06-22T20:15:27Z</updated_at>
</gateway>
Create (provision) a gateway to process simulated card data and transactions in the authenticated environment. A sandbox gateway should be used to test out complex integrations like 3D Secure. It is recommended that you create all your sandboxed gateways in their own environment and add a description that highlights that the gateway is intended for sandbox based transactions only. When interacting with a sandbox gateway, you need to ensure that you’re not using real payment method data; instead you should be using the gateway’s test payment method data. Here is an example of Stripe’s sandbox payment method data from their testing guide.
Sandbox gateways are created using the credentials required for that gateway, meaning each call is slightly different depending on the gateway’s API requirements. This example uses Stripe, but any supported gateway will have a similar call.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ gateway_type required |
The type of gateway, e.g., stripe, braintree, etc…. You can find the list of supported gateways and their respective gateway types on this page |
| ❯ gateway specific credential field(s) required |
The merchant credentials required for this type of gateway. Stripe has login, but your gateway type will most likely require a different set of credentials. Please reference the gateway’s documentation to determine the appropriate credential(s) to pass here. |
| ❯ description | A description of the gateway. Useful to differentiate between multiple gateways of the same type provisioned within your system. EG: “Sandboxed gateway, not for production use.” |
| ❯ merchant_profile_key | optional The token for an existing Merchant Profile in your environment. Useful for organizing gateways in an environment with multiple merchants, or associating merchant data with gateway transactions. |
| ❯ sandbox | optional true or false (false if omitted). Useful to test out a gateway’s sandbox mode, this is recommended in situations where the gateway integration is difficult and where you don’t want to execute real transactions. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ token | The token identifying the provisioned gateway at Spreedly |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway |
| ❯ description | The description of the provisioned gateway |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the provisioned gateway |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the provisioned gateway |
| ❯ state | The storage state of the gateway (retained, redacted, etc…) |
| ❯ sandbox | If the gateway was created in sandbox mode or not |
| ❯ redacted | If this gateway is redacted or not |
| ❯ credentials | The non-sensitive credentials used for this gateway |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
Create production gateway
POST /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "stripe",
"login": "your Stripe API secret",
"sandbox": true
}
}
<gateway>
<gateway_type>stripe</gateway_type>
<login>your api secret key</login>
<sandbox>true</sandbox>
</gateway>
HTTPS/1.1 201 Created
{
"gateway": {
"token": "UlSR3GCgSBzryKio8zeIF4aIHqm",
"gateway_type": "stripe",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"third_party_token",
"apple_pay",
"bank_account",
"google_pay"
],
"state": "retained",
"created_at": "2022-06-22T20:15:29Z",
"updated_at": "2022-06-22T20:15:29Z",
"name": "Stripe",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"void",
"verify",
"3dsecure_purchase",
"3dsecure_authorize",
"store",
"remove"
],
"credentials": [
],
"gateway_settings": {
"webhook_id": null,
"version_override": null
},
"gateway_specific_fields": [
"receipt_email",
"radar_session_id",
"skip_radar_rules",
"application_fee",
"stripe_account",
"metadata",
"idempotency_key",
"reason",
"refund_application_fee",
"refund_fee_amount",
"reverse_transfer",
"account_id",
"customer_id",
"validate",
"make_default",
"statement_description",
"statement_descriptor_suffix",
"destination",
"destination_amount",
"merchant_reference",
"customer_reference",
"shipping_address_zip",
"shipping_from_zip",
"shipping_amount",
"line_items",
"transfer_destination",
"transfer_amount",
"transfer_group",
"on_behalf_of",
"application_fee_amount",
"recurring"
],
"redacted": false,
"sandbox": true,
"mode": "default"
}
}
<gateway>
<token>XalHWUjzXpdSfHUTGUYtFvtEbll</token>
<gateway_type>stripe</gateway_type>
<name>Stripe</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">false</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
<webhook_id nil="true"></webhook_id>
<version_override nil="true"></version_override>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>receipt_email</gateway_specific_field>
<gateway_specific_field>radar_session_id</gateway_specific_field>
<gateway_specific_field>skip_radar_rules</gateway_specific_field>
<gateway_specific_field>application_fee</gateway_specific_field>
<gateway_specific_field>stripe_account</gateway_specific_field>
<gateway_specific_field>metadata</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>reason</gateway_specific_field>
<gateway_specific_field>refund_application_fee</gateway_specific_field>
<gateway_specific_field>refund_fee_amount</gateway_specific_field>
<gateway_specific_field>reverse_transfer</gateway_specific_field>
<gateway_specific_field>account_id</gateway_specific_field>
<gateway_specific_field>customer_id</gateway_specific_field>
<gateway_specific_field>validate</gateway_specific_field>
<gateway_specific_field>make_default</gateway_specific_field>
<gateway_specific_field>statement_description</gateway_specific_field>
<gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
<gateway_specific_field>destination</gateway_specific_field>
<gateway_specific_field>destination_amount</gateway_specific_field>
<gateway_specific_field>merchant_reference</gateway_specific_field>
<gateway_specific_field>customer_reference</gateway_specific_field>
<gateway_specific_field>shipping_address_zip</gateway_specific_field>
<gateway_specific_field>shipping_from_zip</gateway_specific_field>
<gateway_specific_field>shipping_amount</gateway_specific_field>
<gateway_specific_field>line_items</gateway_specific_field>
<gateway_specific_field>transfer_destination</gateway_specific_field>
<gateway_specific_field>transfer_amount</gateway_specific_field>
<gateway_specific_field>transfer_group</gateway_specific_field>
<gateway_specific_field>on_behalf_of</gateway_specific_field>
<gateway_specific_field>application_fee_amount</gateway_specific_field>
<gateway_specific_field>recurring</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">true</sandbox>
<mode>default</mode>
<created_at type="dateTime">2022-06-22T20:15:27Z</created_at>
<updated_at type="dateTime">2022-06-22T20:15:27Z</updated_at>
</gateway>
Create (provision) a gateway to process real card data and transactions in the authenticated environment.
Production gateways are created using the credentials required for that gateway, meaning each call is slightly different depending on the gateway’s API requirements. This example uses Stripe, but any supported gateway will have a similar call.
suggestion If you’d like to test out a gateway in test / sandbox mode, you can do so by including the sandbox parameter when creating a gateway. If you do so, you’ll need to check the gateway’s documentation to determine test cards in sandbox mode. Once you’re satisfied with your testing and ready for a real transaction, you’ll need to create another gateway without the sandbox parameter.
Example sandbox workflow
- create a gateway in sandbox mode
- verify your integration with Spreedly and the gateway
- create another gateway without sandbox mode
- start transacting with real payments
note If you wish to go straight to production with transactions, skip the first two steps.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ gateway_type required |
The type of gateway, e.g., stripe, braintree, etc…. You can find the list of supported gateways and their respective gateway types on this page |
| ❯ gateway specific credential field(s) required |
The merchant credentials required for this type of gateway. Stripe has login, but your gateway type will most likely require a different set of credentials. Please reference the gateway’s documentation to determine the appropriate credential(s) to pass here. |
| ❯ description | A description of the gateway. Useful to differentiate between multiple gateways of the same type provisioned within your system. |
| ❯ merchant_profile_key | optional The token for an existing Merchant Profile in your environment. Useful to organize gateways in an environment with multiple merchants, or to associate merchant data with gateway transactions. |
| ❯ sub_merchant_key | optional The token for an existing Sub-merchant in your environment. Useful for tagging the transactions through this gateway with the sub-merchant who transacts through the gateway. |
| ❯ sandbox | optional true or false. Useful to test out a gateway’s sandbox mode, this is recommended in situations where the gateway integration is difficult and where you don’t want to execute real transactions. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ token | The token identifying the provisioned gateway at Spreedly |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway |
| ❯ description | The description of the provisioned gateway |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the provisioned gateway |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the provisioned gateway |
| ❯ state | The storage state of the gateway (retained, redacted, etc…) |
| ❯ sandbox | If the gateway was created in sandbox mode or not |
| ❯ redacted | If this gateway is redacted or not |
| ❯ credentials | The non-sensitive credentials used for this gateway |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
Show
GET /v1/gateways/<gateway_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"gateway": {
"token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"google_pay"
],
"state": "retained",
"created_at": "2017-06-26T16:57:27Z",
"updated_at": "2017-11-27T20:04:25Z",
"name": "Spreedly Test",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"offsite_synchronous_purchase",
"offsite_synchronous_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials"
],
"credentials": [
],
"gateway_settings": {
},
"gateway_specific_fields": [
"simulate_error",
"simulate_decline",
"idempotency_key",
"mit_override_demo"
],
"redacted": false,
"sandbox": false,
"mode": "default"
}
}
<gateway>
<token>T11bJAANtTWnxl36GYjKWvbNK0g</token>
<gateway_type>test</gateway_type>
<name>Spreedly Test</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_reference_authorization type="boolean">true</supports_reference_authorization>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>simulate_error</gateway_specific_field>
<gateway_specific_field>simulate_decline</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>mit_override_demo</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>sprel</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2017-06-26T16:57:27Z</created_at>
<updated_at type="dateTime">2017-11-27T20:04:25Z</updated_at>
</gateway>
Get a gateway with the given token.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ token | The token identifying the provisioned gateway at Spreedly |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway |
| ❯ description | The description of the provisioned gateway |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the provisioned gateway |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the provisioned gateway |
| ❯ state | The storage state of the gateway (retained, redacted, etc…) |
| ❯ sandbox | If the gateway was created in sandbox mode or not |
| ❯ redacted | If this gateway is redacted or not |
| ❯ credentials | The non-sensitive credentials used for this gateway |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
Update
PUT /v1/gateways/<gateway_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"login": "updated Stripe API secret"
}
}
<gateway>
<login>updated Stripe API secret</login>
</gateway>
HTTPS/1.1 200 OK
{
"gateway": {
"token": "YhtVn4t7MJRd6ukjktiHn6RXX5P",
"gateway_type": "stripe",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"third_party_token",
"apple_pay",
"bank_account",
"google_pay"
],
"state": "retained",
"created_at": "2021-06-01T19:13:25Z",
"updated_at": "2022-03-16T17:58:13Z",
"name": "Stripe",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"void",
"verify",
"3dsecure_purchase",
"3dsecure_authorize",
"store",
"remove"
],
"credentials": [
],
"gateway_settings": {
"webhook_id": null,
"version_override": null
},
"gateway_specific_fields": [
"receipt_email",
"radar_session_id",
"skip_radar_rules",
"application_fee",
"stripe_account",
"metadata",
"idempotency_key",
"reason",
"refund_application_fee",
"refund_fee_amount",
"reverse_transfer",
"account_id",
"customer_id",
"validate",
"make_default",
"statement_description",
"statement_descriptor_suffix",
"destination",
"destination_amount",
"merchant_reference",
"customer_reference",
"shipping_address_zip",
"shipping_from_zip",
"shipping_amount",
"line_items",
"transfer_destination",
"transfer_amount",
"transfer_group",
"on_behalf_of",
"application_fee_amount",
"recurring"
],
"redacted": false,
"sandbox": false,
"mode": "default"
}
}
<gateway>
<token>YhtVn4t7MJRd6ukjktiHn6RXX5P</token>
<gateway_type>stripe</gateway_type>
<name>Stripe</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">false</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
<webhook_id nil="true"></webhook_id>
<version_override nil="true"></version_override>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>receipt_email</gateway_specific_field>
<gateway_specific_field>radar_session_id</gateway_specific_field>
<gateway_specific_field>skip_radar_rules</gateway_specific_field>
<gateway_specific_field>application_fee</gateway_specific_field>
<gateway_specific_field>stripe_account</gateway_specific_field>
<gateway_specific_field>metadata</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>reason</gateway_specific_field>
<gateway_specific_field>refund_application_fee</gateway_specific_field>
<gateway_specific_field>refund_fee_amount</gateway_specific_field>
<gateway_specific_field>reverse_transfer</gateway_specific_field>
<gateway_specific_field>account_id</gateway_specific_field>
<gateway_specific_field>customer_id</gateway_specific_field>
<gateway_specific_field>validate</gateway_specific_field>
<gateway_specific_field>make_default</gateway_specific_field>
<gateway_specific_field>statement_description</gateway_specific_field>
<gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
<gateway_specific_field>destination</gateway_specific_field>
<gateway_specific_field>destination_amount</gateway_specific_field>
<gateway_specific_field>merchant_reference</gateway_specific_field>
<gateway_specific_field>customer_reference</gateway_specific_field>
<gateway_specific_field>shipping_address_zip</gateway_specific_field>
<gateway_specific_field>shipping_from_zip</gateway_specific_field>
<gateway_specific_field>shipping_amount</gateway_specific_field>
<gateway_specific_field>line_items</gateway_specific_field>
<gateway_specific_field>transfer_destination</gateway_specific_field>
<gateway_specific_field>transfer_amount</gateway_specific_field>
<gateway_specific_field>transfer_group</gateway_specific_field>
<gateway_specific_field>on_behalf_of</gateway_specific_field>
<gateway_specific_field>application_fee_amount</gateway_specific_field>
<gateway_specific_field>recurring</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2021-06-01T19:13:25Z</created_at>
<updated_at type="dateTime">2022-03-16T17:58:12Z</updated_at>
</gateway>
Update a gateway.
Updating a redacted gateway’s credentials will set its state back to retained, allowing it to be used for transactions.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ gateway specific credential field(s) required |
The merchant credentials required for this type of gateway. Stripe has login, but your gateway type will most likely require a different set of credentials. Please reference the gateway’s documentation to determine the appropriate credential(s) to pass here. |
| ❯ description | A description of the gateway. Useful to differentiate between multiple gateways of the same type provisioned within your system. |
| ❯ merchant_profile_key | optional The token for an existing Merchant Profile in your environment. Useful to organize gateways in an environment with multiple merchants, or to associate merchant data with gateway transactions. |
| ❯ sub_merchant_key | optional The token for an existing Sub-merchant in your environment. Useful for tagging the transactions through this gateway with the sub-merchant who transacts through the gateway. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| gateway | Root element |
| ❯ token | The token identifying the provisioned gateway at Spreedly |
| ❯ name | The human readable name of the gateway |
| ❯ gateway_type | The type (short name) of the gateway. Use this value when provisioning a gateway |
| ❯ description | The description of the provisioned gateway |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the provisioned gateway |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the provisioned gateway |
| ❯ state | The storage state of the gateway (retained, redacted, etc…) |
| ❯ sandbox | If the gateway was created in sandbox mode or not |
| ❯ redacted | If this gateway is redacted or not |
| ❯ credentials | The non-sensitive credentials used for this gateway |
| ❯ gateway_settings | The non-credential fields that can be specified at the gateway level, and included in all transactions |
| ❯ characteristics | A list of operations (such as purchase, capture etc…) that the gateway supports |
| ❯ payment_methods | A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports |
| ❯ gateway_specific_fields | The list of gateway specific fields that can be specified in supported gateway transactions |
Retain
PUT /v1/gateways/<gateway_token>/retain.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"transaction": {
"token": "9EwxsDWR0g3EsE686j8qsX5gAuS",
"created_at": "2020-04-03T18:22:31Z",
"updated_at": "2020-04-03T18:22:31Z",
"succeeded": true,
"transaction_type": "RetainGateway",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway": {
"token": "RpnIaNabjy9E8Itba4JPV4Zgapz",
"gateway_type": "authorize_net",
"description": null,
"payment_methods": [
"credit_card",
"bank_account",
"apple_pay",
"third_party_token"
],
"state": "retained",
"created_at": "2020-04-03T18:22:31Z",
"updated_at": "2020-04-03T18:22:31Z",
"name": "Authorize.Net",
"login": "Your Authorize.Net API Login ID",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"verify",
"store",
"fraud_review"
],
"credentials": [
{
"name": "login",
"value": "Your Authorize.Net API Login ID"
}
],
"gateway_settings": {
"opt_out_recurring_default": null
},
"gateway_specific_fields": [
"customer_id",
"customer_profile_id",
"duplicate_window",
"disable_partial_auth",
"market_type",
"recurring",
"email_customer",
"header_email_receipt",
"line_items",
"po_number",
"tax_exempt",
"tax",
"duty",
"shipping",
"transaction_id",
"require_billing_address",
"customer_payment_profile_id",
"ship_from_address",
"summary_commodity_code",
"authentication_indicator",
"cardholder_authentication_value"
],
"redacted": false,
"sandbox": false
}
}
}
<transaction>
<token>7fQWQ3hA9sv80Gl5pLff4KPkG2d</token>
<created_at type="dateTime">2020-04-03T18:22:31Z</created_at>
<updated_at type="dateTime">2020-04-03T18:22:31Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>RetainGateway</transaction_type>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway>
<token>GULbQX8cBftv3qXyGGKsoowkRDy</token>
<gateway_type>authorize_net</gateway_type>
<name>Authorize.Net</name>
<description nil="true"></description>
<login>Your Authorize.Net API Login ID</login>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">true</supports_fraud_review>
</characteristics>
<credentials>
<credential>
<name>login</name>
<value>Your Authorize.Net API Login ID</value>
</credential>
</credentials>
<gateway_settings>
<opt_out_recurring_default nil="true"></opt_out_recurring_default>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>customer_id</gateway_specific_field>
<gateway_specific_field>customer_profile_id</gateway_specific_field>
<gateway_specific_field>duplicate_window</gateway_specific_field>
<gateway_specific_field>disable_partial_auth</gateway_specific_field>
<gateway_specific_field>market_type</gateway_specific_field>
<gateway_specific_field>recurring</gateway_specific_field>
<gateway_specific_field>email_customer</gateway_specific_field>
<gateway_specific_field>header_email_receipt</gateway_specific_field>
<gateway_specific_field>line_items</gateway_specific_field>
<gateway_specific_field>po_number</gateway_specific_field>
<gateway_specific_field>tax_exempt</gateway_specific_field>
<gateway_specific_field>tax</gateway_specific_field>
<gateway_specific_field>duty</gateway_specific_field>
<gateway_specific_field>shipping</gateway_specific_field>
<gateway_specific_field>transaction_id</gateway_specific_field>
<gateway_specific_field>require_billing_address</gateway_specific_field>
<gateway_specific_field>customer_payment_profile_id</gateway_specific_field>
<gateway_specific_field>ship_from_address</gateway_specific_field>
<gateway_specific_field>summary_commodity_code</gateway_specific_field>
<gateway_specific_field>authentication_indicator</gateway_specific_field>
<gateway_specific_field>cardholder_authentication_value</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>third_party_token</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<created_at type="dateTime">2020-04-03T18:22:30Z</created_at>
<updated_at type="dateTime">2020-04-03T18:22:31Z</updated_at>
</gateway>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway | The gateway that was redacted |
| ❯❯ redacted | If the gateway is redacted |
| ❯❯ state | The new state of the gateway (retained) |
Redact
PUT /v1/gateways/<gateway_token>/redact.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"transaction": {
"token": "kKMybjJETZqTBhyVjr71zAE5Cf",
"created_at": "2020-04-03T18:22:29Z",
"updated_at": "2020-04-03T18:22:29Z",
"succeeded": true,
"transaction_type": "RedactGateway",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway": {
"token": "Dj9T30zWhNRIlJbfdcSCbw2o6Yp",
"gateway_type": "authorize_net",
"description": null,
"payment_methods": [
"credit_card",
"bank_account",
"apple_pay",
"third_party_token"
],
"state": "redacted",
"created_at": "2020-04-03T18:22:29Z",
"updated_at": "2020-04-03T18:22:29Z",
"name": "Authorize.Net",
"login": "Your Authorize.Net API Login ID",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"verify",
"store",
"fraud_review"
],
"credentials": [
{
"name": "login",
"value": "Your Authorize.Net API Login ID"
}
],
"gateway_settings": {
"opt_out_recurring_default": null
},
"gateway_specific_fields": [
"customer_id",
"customer_profile_id",
"duplicate_window",
"disable_partial_auth",
"market_type",
"recurring",
"email_customer",
"header_email_receipt",
"line_items",
"po_number",
"tax_exempt",
"tax",
"duty",
"shipping",
"transaction_id",
"require_billing_address",
"customer_payment_profile_id",
"ship_from_address",
"summary_commodity_code",
"authentication_indicator",
"cardholder_authentication_value"
],
"redacted": true,
"sandbox": false
}
}
}
<transaction>
<token>GQxQpU4iKeYkUzk8Y8lKFDel4Dp</token>
<created_at type="dateTime">2020-04-03T18:22:28Z</created_at>
<updated_at type="dateTime">2020-04-03T18:22:28Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>RedactGateway</transaction_type>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway>
<token>HF664DtDUtyxHyAS4qHgqUuy2kM</token>
<gateway_type>authorize_net</gateway_type>
<name>Authorize.Net</name>
<description nil="true"></description>
<login>Your Authorize.Net API Login ID</login>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">true</supports_fraud_review>
</characteristics>
<credentials>
<credential>
<name>login</name>
<value>Your Authorize.Net API Login ID</value>
</credential>
</credentials>
<gateway_settings>
<opt_out_recurring_default nil="true"></opt_out_recurring_default>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>customer_id</gateway_specific_field>
<gateway_specific_field>customer_profile_id</gateway_specific_field>
<gateway_specific_field>duplicate_window</gateway_specific_field>
<gateway_specific_field>disable_partial_auth</gateway_specific_field>
<gateway_specific_field>market_type</gateway_specific_field>
<gateway_specific_field>recurring</gateway_specific_field>
<gateway_specific_field>email_customer</gateway_specific_field>
<gateway_specific_field>header_email_receipt</gateway_specific_field>
<gateway_specific_field>line_items</gateway_specific_field>
<gateway_specific_field>po_number</gateway_specific_field>
<gateway_specific_field>tax_exempt</gateway_specific_field>
<gateway_specific_field>tax</gateway_specific_field>
<gateway_specific_field>duty</gateway_specific_field>
<gateway_specific_field>shipping</gateway_specific_field>
<gateway_specific_field>transaction_id</gateway_specific_field>
<gateway_specific_field>require_billing_address</gateway_specific_field>
<gateway_specific_field>customer_payment_profile_id</gateway_specific_field>
<gateway_specific_field>ship_from_address</gateway_specific_field>
<gateway_specific_field>summary_commodity_code</gateway_specific_field>
<gateway_specific_field>authentication_indicator</gateway_specific_field>
<gateway_specific_field>cardholder_authentication_value</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>third_party_token</payment_method>
</payment_methods>
<state>redacted</state>
<redacted type="boolean">true</redacted>
<sandbox type="boolean">false</sandbox>
<created_at type="dateTime">2020-04-03T18:22:28Z</created_at>
<updated_at type="dateTime">2020-04-03T18:22:28Z</updated_at>
</gateway>
</transaction>
Redact (strip of any sensitive credentials and make inactive) a provisioned gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway | The gateway that was redacted |
| ❯❯ redacted | If the gateway is now redacted |
| ❯❯ state | The new state of the gateway (redacted) |
Transactions
GET /v1/gateways/<gateway_token>/transactions.<format>?order=desc HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"transactions": [
{
"on_test_gateway": true,
"created_at": "2021-06-01T18:12:58Z",
"updated_at": "2021-06-01T18:12:58Z",
"succeeded": true,
"state": "succeeded",
"token": "HTDLYnmo52ZEKrpLgW5mmFw3Mss",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "50",
"gateway_latency_ms": 0,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"warning": null,
"application_id": null,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2021-06-01T18:12:58Z",
"updated_at": "2021-06-01T18:12:58Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2021-06-01T18:12:57Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
]
}
<transactions>
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2021-06-01T18:12:58Z</created_at>
<updated_at type="dateTime">2021-06-01T18:12:58Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>HTDLYnmo52ZEKrpLgW5mmFw3Mss</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<merchant_profile_key nil="true"></merchant_profile_key>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>50</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<stored_credential_initiator nil="true"></stored_credential_initiator>
<stored_credential_reason_type nil="true"></stored_credential_reason_type>
<warning nil="true"></warning>
<application_id nil="true"></application_id>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2021-06-01T18:12:58Z</created_at>
<updated_at type="dateTime">2021-06-01T18:12:58Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at>2017-06-26T17:04:38Z</created_at>
<updated_at>2021-06-01T18:12:57Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
</transactions>
Get an ordered and paginated list of transactions executed against a specific gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
| state | The transaction state on which to filter the returned list. Can be one of succeeded, failed, gateway_processing_failed, gateway_processing_result_unknown. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
Receivers
List supported receivers
GET /v1/receivers_options.<format>?published=true HTTPS/1.1
Host: core.spreedly.com
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"receivers": [
{
"receiver_type": "a1_payments",
"name": "A1payments Receiver",
"hostnames": "https://www.a1payments.com",
"company_name": "A1 Payments"
},
{
"receiver_type": "abg_direct",
"name": "Abgdirect Receiver",
"hostnames": "https://services.carrental.com,https://qaservices.carrental.com",
"company_name": "ABG Direct"
}
]
}
<receivers>
<receiver>
<receiver_type>a1_payments</receiver_type>
<name>A1payments Receiver</name>
<hostnames>https://www.a1payments.com</hostnames>
<company_name>A1 Payments</company_name>
</receiver>
<receiver>
<receiver_type>abg_direct</receiver_type>
<name>Abgdirect Receiver</name>
<hostnames>https://services.carrental.com,https://qaservices.carrental.com</hostnames>
<company_name>ABG Direct</company_name>
</receiver>
</receivers>
Retrieve a list of all payment method distribution receivers, and their properties, supported by Spreedly.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| receivers | Root element |
| ❯ name | The human readable name of the receiver |
| ❯ receiver_type | The type (short name) of the receiver. Use this value when provisioning a receiver. |
| ❯ hostnames | The urls used to interact with the receiver |
| ❯ company_name | The name of the company providing the receiver |
List created receivers
GET /v1/receivers.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"receivers": [
{
"company_name": "TEST",
"receiver_type": "test",
"token": "2kAEQYkLqRJLJZoyGvF9c8gVieo",
"hostnames": "https://spreedly-echo.herokuapp.com/",
"state": "retained",
"created_at": "2017-06-22T21:17:45Z",
"updated_at": "2018-04-20T12:10:52Z",
"credentials": null
},
{
"company_name": "TEST",
"receiver_type": "test",
"token": "XYEV709EQHWUkwFyTcRx1N6WXKz",
"hostnames": "https://spreedly-echo.herokuapp.com/",
"state": "retained",
"created_at": "2017-06-22T21:20:21Z",
"updated_at": "2018-04-20T12:12:38Z",
"credentials": [
{
"name": "app-id",
"value": "1234",
"safe": "true"
},
{
"name": "app-secret",
"safe": "false"
}
]
}
]
}
<receivers>
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>2kAEQYkLqRJLJZoyGvF9c8gVieo</token>
<hostnames>https://spreedly-echo.herokuapp.com/</hostnames>
<state>retained</state>
<created_at type="dateTime">2017-06-22T21:17:45Z</created_at>
<updated_at type="dateTime">2018-04-20T12:10:52Z</updated_at>
<credentials nil="true"></credentials>
</receiver>
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>XYEV709EQHWUkwFyTcRx1N6WXKz</token>
<hostnames>https://spreedly-echo.herokuapp.com/</hostnames>
<state>retained</state>
<created_at type="dateTime">2017-06-22T21:20:21Z</created_at>
<updated_at type="dateTime">2018-04-20T12:12:38Z</updated_at>
<credentials type="array">
<credential>
<name>app-id</name>
<value>1234</value>
<safe>true</safe>
</credential>
<credential>
<name>app-secret</name>
<safe>false</safe>
</credential>
</credentials>
</receiver>
</receivers>
Retrieve an ordered and paginated list of all receivers in the authenticated environment.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| receivers | Root element |
| ❯ company_name | The name of the company providing the receiver |
| ❯ token | The token uniquely identifying this receiver at Spreedly |
| ❯ receiver_type | The type of receiver |
| ❯ hostnames | The allowed list of hostnames to which payment methods can be delivered |
| ❯ state | The storage state of the payment method. Can be one of retained or redacted. By default, receivers are created in the retained state and must be explicitly redacted if they are no longer required. |
Create HTTP receiver
POST /v1/receivers.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"receiver": {
"receiver_type": "test",
"hostnames": "https://spreedly-echo.herokuapp.com",
"credentials": [
{
"name": "app-id",
"value": 1234,
"safe": true
},
{
"name": "app-secret",
"value": 5678
}
]
}
}
<receiver>
<receiver_type>test</receiver_type>
<hostnames>https://spreedly-echo.herokuapp.com</hostnames>
<credentials>
<credential>
<name>app-id</name>
<value>1234</value>
<safe>true</safe>
</credential>
<credential>
<name>app-secret</name>
<value>5678</value>
</credential>
</credentials>
</receiver>
HTTPS/1.1 201 Created
{
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "TdXjq6sqBHpD1200iIvUhYy9x50",
"hostnames": "https://spreedly-echo.herokuapp.com",
"state": "retained",
"created_at": "2020-02-13T18:38:04Z",
"updated_at": "2020-02-13T18:38:04Z",
"credentials": [
{
"name": "app-id",
"value": 1234,
"safe": true
},
{
"name": "app-secret",
"safe": false
}
]
}
}
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>NG7rSGp3MPJIWEXwKxZ5sr7tgvj</token>
<hostnames>https://spreedly-echo.herokuapp.com</hostnames>
<state>retained</state>
<created_at type="dateTime">2020-02-13T18:38:04Z</created_at>
<updated_at type="dateTime">2020-02-13T18:38:04Z</updated_at>
<credentials type="array">
<credential>
<name>app-id</name>
<value>1234</value>
<safe>true</safe>
</credential>
<credential>
<name>app-secret</name>
<safe>false</safe>
</credential>
</credentials>
</receiver>
Create a receiver for use in payment method distribution.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| receiver | Root element |
| ❯ receiver_type required |
The type of receiver to provision. Can be test for a test receiver, or any one of the other supported production receiver types. |
| ❯ hostnames | Allowed list of hosts that the receiver can send payments to. Supports a comma separated list of hostnames if multiple are required. Hostnames should include the protocol and domain, but not the path, e.g., https://testing.receiver.com (https is required). If provided for a test receiver, we will validate the delivery URL against the list of hostnames when simulating delivery to the receiver. Production receivers can omit hostnames as their values are hard-coded. |
| ❯ credentials | Sensitive values that should be securely stored and made available to the request template at time of delivery |
| ❯❯ name | The name of the credential. This will be the name of the variable in the delivery request template. |
| ❯❯ value | The value of the credential. This will be the value substituted in for the credential variable in the delivery request template. |
| ❯❯ safe default: false |
Set to true if the credential is not a sensitive value (e.g., a user name). Otherwise it is assumed to be a sensitive value and will not be echoed back in API responses. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| receiver | Root element |
| ❯ company_name | The name of the company providing the receiver |
| ❯ token | The token uniquely identifying this receiver at Spreedly |
| ❯ receiver_type | The type of receiver |
| ❯ hostnames | The allowed list of hostnames to which payment methods can be delivered |
| ❯ state | The storage state of the payment method. Can be one of retained or redacted. By default, receivers are created in the retained state and must be explicitly redacted if they are no longer required. |
| ❯ credentials | One or more name/value pairs used to authenticate with the receiver. Only credentials marked as safe will have their values echoed. |
Create SFTP receiver
POST /v1/receivers.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"receiver": {
"receiver_type": "test",
"hostnames": "sftp://testserver.com",
"protocol": {
"user": "test_user",
"password": "test_password"
}
}
}
<receiver>
<receiver_type>test</receiver_type>
<hostnames>sftp://testserver.com</hostnames>
<protocol>
<user>test_user</user>
<password>test_password</password>
</protocol>
</receiver>
HTTPS/1.1 201 Created
{
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "Rz3rhs0J7V2UW41egNYTBJiMpUQ",
"hostnames": "sftp://testserver.com",
"state": "retained",
"created_at": "2018-04-20T12:58:03Z",
"updated_at": "2018-04-20T12:58:03Z",
"credentials": null,
"protocol": {
"user": "test_user"
}
}
}
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>9X7emTBWC90OjvcYBkmuJZM6HbC</token>
<hostnames>sftp://testserver.com</hostnames>
<state>retained</state>
<created_at type="dateTime">2018-04-20T12:58:02Z</created_at>
<updated_at type="dateTime">2018-04-20T12:58:02Z</updated_at>
<credentials nil="true"></credentials>
<protocol>
<user>test_user</user>
</protocol>
</receiver>
Create a receiver for use in payment method distribution.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| receiver | Root element |
| ❯ receiver_type required |
The type of receiver to provision. Can be test for a test receiver, or any one of the other supported production receiver types. |
| ❯ protocol required for SFTP receivers |
a hash of protocol values, currently only used for the SFTP protocol. e.g. sftp://user:password@127.0.0.0 |
| ❯ hostnames | Allowed list of hosts that the receiver can send payments to. Supports a comma separated list of hostnames if multiple are required. Hostnames should include the protocol and domain, but not the path, e.g., sftp://testing.receiver.com. If provided for a test receiver, we will validate the delivery URL against the list of hostnames when simulating delivery to the receiver. Production receivers can omit hostnames as their values are hard-coded. |
| ❯❯ user | The user value. |
| ❯❯ password | The password value. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| receiver | Root element |
| ❯ company_name | The name of the company providing the receiver |
| ❯ token | The token uniquely identifying this receiver at Spreedly |
| ❯ receiver_type | The type of receiver |
| ❯ hostnames | The allowed list of hostnames to which payment methods can be delivered |
| ❯ state | The storage state of the payment method. Can be one of retained or redacted. By default, receivers are created in the retained state and must be explicitly redacted if they are no longer required. |
| ❯ protocol_user | The user value used to authenticate with the SFTP receiver. |
Show receiver
GET /v1/receivers/<receiver_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "JhGsltr85iI0C2CnrSFA2nmjAOO",
"hostnames": "https://spreedly-echo.herokuapp.com",
"state": "retained",
"created_at": "2017-07-27T17:55:34Z",
"updated_at": "2017-07-27T17:55:34Z",
"credentials": null
}
}
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>T4WSwkjLmmBnnKYNeeGCb7FmPxB</token>
<hostnames>https://spreedly-echo.herokuapp.com</hostnames>
<state>retained</state>
<created_at type="dateTime">2018-04-04T15:36:17Z</created_at>
<updated_at type="dateTime">2018-04-04T15:36:17Z</updated_at>
<credentials nil="true"></credentials>
</receiver>
Get a receiver with the given token.
URL Parameters
| Parameter | Description |
|---|---|
| receiver_token required |
The token of the receiver at Spreedly |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| receiver | Root element |
| ❯ company_name | The name of the company providing the receiver |
| ❯ token | The token uniquely identifying this receiver at Spreedly |
| ❯ receiver_type | The type of receiver |
| ❯ hostnames | The allowed list of hostnames to which payment methods can be delivered |
| ❯ state | The storage state of the payment method. Can be one of retained or redacted. By default, receivers are created in the retained state and must be explicitly redacted if they are no longer required. |
Update receiver
PUT /v1/receivers/<receiver_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"receiver": {
"credentials": [
{
"name": "app-id",
"value": "abcd",
"safe": true
},
{
"name": "app-secret",
"value": "efgh"
}
]
}
}
<receiver>
<credentials>
<credential>
<name>app-id</name>
<value>abcd</value>
<safe>true</safe>
</credential>
<credential>
<name>app-secret</name>
<value>efgh</value>
</credential>
</credentials>
</receiver>
HTTPS/1.1 200 OK
{
"transaction": {
"token": "4844UmKDKTnRLSu203SjJ5vaHSH",
"created_at": "2017-07-27T17:55:36Z",
"updated_at": "2017-07-27T17:55:36Z",
"succeeded": true,
"transaction_type": "UpdatePaymentMethodReceiver",
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "IXPvgTDJUxCKwzXdYn6shVVjPrd",
"hostnames": "https://spreedly-echo.herokuapp.com",
"state": "retained",
"created_at": "2017-07-27T17:55:35Z",
"updated_at": "2017-07-27T17:55:36Z",
"credentials": [
{
"name": "app-id",
"value": "abcd",
"safe": true
},
{
"name": "app-secret",
"safe": "false"
}
]
}
}
}
<transaction>
<token>BIqYM6q9kideDE8Xwj8LbMKGvvF</token>
<created_at type="dateTime">2017-07-27T17:55:37Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:37Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>UpdatePaymentMethodReceiver</transaction_type>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>I915nS7vmJnqPN9twDHW9blRaq0</token>
<hostnames>https://spreedly-echo.herokuapp.com</hostnames>
<state>retained</state>
<created_at type="dateTime">2017-07-27T17:55:36Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:37Z</updated_at>
<credentials type="array">
<credential>
<name>app-id</name>
<value>abcd</value>
<safe>true</safe>
</credential>
<credential>
<name>app-secret</name>
<safe>false</safe>
</credential>
</credentials>
</receiver>
</transaction>
Update a receiver with new credentials.
URL Parameters
| Parameter | Description |
|---|---|
| receiver_token required |
The token of the receiver at Spreedly |
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| receiver | Root element |
| ❯ credentials required |
Sensitive values that should be securely stored and made available to the request template at time of delivery |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ receiver | Updated receiver |
| ❯❯ token | The token uniquely identifying this receiver at Spreedly |
| ❯❯ receiver_type | The type of receiver |
| ❯❯ hostnames | The allowed list of hostnames to which payment methods can be delivered |
| ❯❯ state | The storage state of the payment method. Can be one of retained or redacted. By default, receivers are created in the retained state and must be explicitly redacted if they are no longer required. |
| ❯❯ credentials | One or more name/value pairs used to authenticate with the receiver. Only credentials marked as safe will have their values echoed. |
Redact receiver
PUT /v1/receivers/<receiver_token>/redact.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"transaction": {
"token": "GX7M1jZKAdsYGVrQSvvMw2gLHQx",
"created_at": "2017-07-27T17:55:33Z",
"updated_at": "2017-07-27T17:55:33Z",
"succeeded": true,
"transaction_type": "RedactPaymentMethodReceiver",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "BDNVxsYWxxDVrMQhTsC14r6qASy",
"hostnames": "https://spreedly-echo.herokuapp.com",
"state": "redacted",
"created_at": "2017-07-27T17:55:32Z",
"updated_at": "2017-07-27T17:55:33Z",
"credentials": null
}
}
}
<transaction>
<token>2fetQVEr2aIn9f9lM1tCd2xjUJG</token>
<created_at type="dateTime">2017-07-27T17:55:33Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:33Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>RedactPaymentMethodReceiver</transaction_type>
<message key="messages.transaction_succeeded">Succeeded!</message>
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>J3jPlZXbgZIhLjPGxYqmRiqBQKA</token>
<hostnames>https://spreedly-echo.herokuapp.com</hostnames>
<state>redacted</state>
<created_at type="dateTime">2017-07-27T17:55:33Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:33Z</updated_at>
<credentials nil="true"></credentials>
</receiver>
</transaction>
Redact (strip of any sensitive credentials and make inactive) a receiver.
URL Parameters
| Parameter | Description |
|---|---|
| receiver_token required |
The token of the receiver at Spreedly |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ receiver | Updated receiver |
| ❯❯ token | The token uniquely identifying this receiver at Spreedly |
| ❯❯ receiver_type | The type of receiver |
| ❯❯ hostnames | The allowed list of hostnames to which payment methods can be delivered |
| ❯❯ state | The storage state of the payment method. Can be one of retained or redacted. By default, receivers are created in the retained state and must be explicitly redacted if they are no longer required. |
| ❯❯ credentials | One or more name/value pairs used to authenticate with the receiver. Only credentials marked as safe will have their values echoed. |
Payment Methods
Create credit card
POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"credit_card": {
"first_name": "Joe",
"last_name": "Jones",
"number": "5555555555554444",
"verification_value": "423",
"month": "3",
"year": "2029",
"company": "Acme Inc.",
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313",
"shipping_address1": "33 Lane Road",
"shipping_address2": "Apartment 4",
"shipping_city": "Wanaque",
"shipping_state": "NJ",
"shipping_zip": "31331",
"shipping_country": "US",
"shipping_phone_number": "919.331.3313"
},
"email": "joey@example.com",
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
}
}
}
<payment_method>
<credit_card>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<number>5555555555554444</number>
<verification_value>423</verification_value>
<month>3</month>
<year>2029</year>
<company>Acme Inc.</company>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
<shipping_address1>33 Lane Road</shipping_address1>
<shipping_address2>Apartment 4</shipping_address2>
<shipping_city>Wanaque</shipping_city>
<shipping_state>NJ</shipping_state>
<shipping_zip>31331</shipping_zip>
<shipping_country>US</shipping_country>
<shipping_phone_number>919.331.3313</shipping_phone_number>
</credit_card>
<email>joey@example.com</email>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
</payment_method>
HTTPS/1.1 201 Created
{
"transaction": {
"token": "AXKchwDYMqAmDqDhxCSaEqiHBk0",
"created_at": "2022-04-14T18:15:18Z",
"updated_at": "2022-04-14T18:15:18Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "PTp0nIk2NcqxaTlgsx3Esz2JSAN",
"created_at": "2022-04-14T18:15:18Z",
"updated_at": "2022-04-14T18:15:18Z",
"email": "joey@example.com",
"data": null,
"storage_state": "cached",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"callback_url": null,
"last_four_digits": "4444",
"first_six_digits": "555555",
"card_type": "master",
"first_name": "Joe",
"last_name": "Jones",
"month": 3,
"year": 2029,
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313",
"company": "Acme Inc.",
"full_name": "Joe Jones",
"eligible_for_card_updater": true,
"shipping_address1": "33 Lane Road",
"shipping_address2": "Apartment 4",
"shipping_city": "Wanaque",
"shipping_state": "NJ",
"shipping_zip": "31331",
"shipping_country": "US",
"shipping_phone_number": "919.331.3313",
"issuer_identification_number": "55555555",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "b5fe350d5135ab64a8f3c1097fadefd9effb",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-4444"
}
}
}
<transaction>
<token>IJR7usbdOAmpMkA35Zx7d5eCAwi</token>
<created_at type="dateTime">2022-04-14T18:15:18Z</created_at>
<updated_at type="dateTime">2022-04-14T18:15:18Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>NNgAp50f3BASpah2NLovmIMQDuE</token>
<created_at type="dateTime">2022-04-14T18:15:18Z</created_at>
<updated_at type="dateTime">2022-04-14T18:15:18Z</updated_at>
<email>joey@example.com</email>
<data nil="true"></data>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>4444</last_four_digits>
<first_six_digits>555555</first_six_digits>
<card_type>master</card_type>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<month type="integer">3</month>
<year type="integer">2029</year>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
<company>Acme Inc.</company>
<full_name>Joey Jones</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1>33 Lane Road</shipping_address1>
<shipping_address2>Apartment 4</shipping_address2>
<shipping_city>Wanaque</shipping_city>
<shipping_state>NJ</shipping_state>
<shipping_zip>31331</shipping_zip>
<shipping_country>US</shipping_country>
<shipping_phone_number>919.331.3313</shipping_phone_number>
<issuer_identification_number>55555555</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-4444</number>
<fingerprint>b5fe350d5135ab64a8f3c1097fadefd9effb</fingerprint>
</payment_method>
</transaction>
Add a credit card to the authenticated environment’s vault.
To create a credit card for testing, use one of the test credit card numbers. For more information about testing on Spreedly, please see this guide.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ credit_card | Credit card element |
| ❯❯ first_name required |
The first name of the cardholder |
| ❯❯ last_name required |
The last name of the cardholder |
| ❯❯ number required |
The full card number |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
| ❯❯ month required |
The expiration month of the card |
| ❯❯ year required |
The expiration year of the card |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the cardholder. If provided, will be parsed to determine first_name and last_name. If “full_name” is entered with only a single name, “first_name” will be populated with “Not Provided” and “last_name” will be populated with the provided name. |
| ❯❯ company | The company name associated with the credit card |
| ❯❯ address1 | The first line of the billing address |
| ❯❯ address2 | The second line of the billing address |
| ❯❯ city | The city of the billing address |
| ❯❯ state | The state of the billing address |
| ❯❯ zip | The zip code of the billing address |
| ❯❯ country | The country code of the billing address |
| ❯❯ phone_number | The phone number of the billing address |
| ❯❯ shipping_address1 | The first line of the shipping address |
| ❯❯ shipping_address2 | The second line of the shipping address |
| ❯❯ shipping_city | The city of the shipping address |
| ❯❯ shipping_state | The state of the shipping address |
| ❯❯ shipping_zip | The zip code of the shipping address |
| ❯❯ shipping_country | The country code of the shipping address |
| ❯❯ shipping_phone_number | The phone number of the shipping address |
| The email address of the customer associated with this credit card | |
| ❯ retained | true if this payment method should be automatically retained on creation |
| ❯ allow_blank_name | true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date | true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date | true if this payment method should skip the expiration date validation requirement |
| ❯ eligible_for_card_updater | true if this payment method should be included in Account Updater |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction (not the created payment method) at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ retained | if the payment method was set to be automatically retained on creation |
| ❯ payment_method | The payment method created as part of this transaction |
| ❯❯ token | The token identifying the newly created payment method in the Spreedly vault |
| ❯❯ storage_state | The storage state of the payment method |
| ❯❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, third_party_token, etc… |
| ❯❯ errors | If the payment method is invalid (missing required fields, etc…), there will be associated error messages here |
| ❯❯ last_four_digits | The last four digits of the credit card number. This can be displayed to the user. |
| ❯❯ first_six_digits | The first six digits of the credit card number. This can be displayed to the user. |
| ❯❯ issuer_identification_number | The numbers of the PAN required to identify the card issuer. |
| ❯❯ verification_value | The obscured verification value (CVV), e.g., XXX or XXXX |
| ❯❯ number | The obscured credit card number, e.g., XXXX-XXXX-XXXX-4444 |
| ❯❯ month | The expiration month |
| ❯❯ year | The expiration year |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Create bank account
POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"bank_account": {
"first_name": "Jon",
"last_name": "Doe",
"bank_name": "Test Bank",
"bank_routing_number": "021000021",
"bank_account_number": "9876543210",
"bank_account_type": "checking",
"bank_account_holder_type": "personal"
},
"email": "jon.doe@example.com",
"data": {
"my_payment_method_identifier": 448,
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
}
}
}
<payment_method>
<bank_account>
<first_name>Jon</first_name>
<last_name>Doe</last_name>
<bank_name>Test Bank</bank_name>
<bank_routing_number>021000021</bank_routing_number>
<bank_account_number>9876543210</bank_account_number>
<bank_account_type>checking</bank_account_type>
<bank_account_holder_type>personal</bank_account_holder_type>
</bank_account>
<email>jon.doe@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
</payment_method>
HTTPS/1.1 201 Created
{
"transaction": {
"token": "Xs0fhYu6CdcaX98CkqTyC8RqvB5",
"created_at": "2023-05-22T19:46:39Z",
"updated_at": "2023-05-22T19:46:39Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "Wvv7vOdcnkeOldsa7tBi69H9tD9",
"created_at": "2023-05-22T19:46:39Z",
"updated_at": "2023-05-22T19:46:39Z",
"email": "jon.doe@example.com",
"data": {
"my_payment_method_identifier": 448,
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "cached",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"callback_url": null,
"full_name": "Jon Doe",
"bank_name": "Test Bank",
"account_type": "checking",
"account_holder_type": "personal",
"routing_number_display_digits": "021",
"account_number_display_digits": "3210",
"first_name": "Jon",
"last_name": "Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"payment_method_type": "bank_account",
"errors": [
],
"routing_number": "021*",
"account_number": "*3210"
}
}
}
<transaction>
<token>NZ8uQMvwLw2ICqiGtJfIVOVYa2j</token>
<created_at type="dateTime">2023-05-22T19:46:39Z</created_at>
<updated_at type="dateTime">2023-05-22T19:46:39Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>4FZOtVeKxuyI7WMOepXi3P3JRwA</token>
<created_at type="dateTime">2023-05-22T19:46:39Z</created_at>
<updated_at type="dateTime">2023-05-22T19:46:39Z</updated_at>
<email>jon.doe@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<full_name>Jon Doe</full_name>
<bank_name>Test Bank</bank_name>
<account_type>checking</account_type>
<account_holder_type>personal</account_holder_type>
<routing_number_display_digits>021</routing_number_display_digits>
<account_number_display_digits>3210</account_number_display_digits>
<first_name>Jon</first_name>
<last_name>Doe</last_name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<payment_method_type>bank_account</payment_method_type>
<errors>
</errors>
<routing_number>021*</routing_number>
<account_number>*3210</account_number>
</payment_method>
</transaction>
Add a bank account/ACH payment type to the authenticated environment’s vault.
To create a bank account for testing, use one of the test bank account numbers. For more information about testing on Spreedly, please see this guide.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ bank_account | Bank account element |
| ❯❯ first_name required |
The first name of the account owner |
| ❯❯ last_name required |
The last name of the account owner |
| ❯❯ bank_routing_number required |
The account routing number |
| ❯❯ bank_account_number required |
The account number |
| ❯❯ bank_name | The name of the bank |
| ❯❯ bank_account_type | The type of account. Can be one of checking or savings. |
| ❯❯ bank_account_holder_type | The account holder type. Can be one business or personal. |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the account owner. If provided, will be parsed to determine first_name and last_name. |
| ❯ retained | true if this payment method should be automatically retained on creation |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
Response Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction (not the created payment method) at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ retained | if the payment method was set to be automatically retained on creation |
| ❯ payment_method | The payment method created as part of this transaction |
| ❯❯ token | The token identifying the newly created payment method in the Spreedly vault |
| ❯❯ storage_state | The storage state of the payment method |
| ❯❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, third_party_token, etc… |
| ❯❯ errors | If the payment method is invalid (missing required fields, etc…), there will be associated error messages here |
| ❯❯ account_type | The type of account. Can be one of checking or savings. |
| ❯❯ account_holder_type | The account holder type. Can be one business or personal. |
| ❯❯ routing_number_display_digits | The obscured (first three digits) routing number. This value can be displayed to users. |
| ❯❯ account_number_display_digits | The obscured (last four digits) account number. This value can be displayed to users. |
Create Apple Pay
POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"apple_pay": {
"payment_data": {
"version": "EC_v1",
"data": "QlzLxRFnNP9/GTaMhBwgmZ2ywntbr9iOcBY4TjPZyNrnCwsJd2cq61bDQjo3agVU0LuEot2VIHHocVrp5jdy0FkxdFhGd+j7hPvutFYGwZPcuuBgROb0beA1wfGDi09I+OWL+8x5+8QPl+y8EAGJdWHXr4CuL7hEj4CjtUhfj5GYLMceUcvwgGaWY7WzqnEO9UwUowlDP9C3cD21cW8osn/IKROTInGcZB0mzM5bVHM73NSFiFepNL6rQtomp034C+p9mikB4nc+vR49oVop0Pf+uO7YVq7cIWrrpgMG7ussnc3u4bmr3JhCNtKZzRQ2MqTxKv/CfDq099JQIvTj8hbqswv1t+yQ5ZhJ3m4bcPwrcyIVej5J241R7dNPu9xVjM6LSOX9KeGZQGud",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTUwMjI0MTgzNTU5WjAvBgkqhkiG9w0BCQQxIgQgohbm8d0A42OAyMnc5fsgQoCNYjtEd/W/dW6+yezIwoAwCgYIKoZIzj0EAwIERzBFAiEAtEkap+JHypwfL1EdabD7RWPZol3na0LhMk9XzLhis0oCIGwxzOhQnMw+Td8WglTMNYcidqeYILTGzn3zMEXmW3j7AAAAAAAA",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQwjaSlnZ3EXpwKfWAd2e1VnbS6vmioMyF6bNcq/Qd65NLQsjrPatzHWbJzG7v5vJtAyrf6WhoNx3C1VchQxYuw==",
"transactionId": "e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371",
"publicKeyHash": "/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI="
}
},
"test_card_number": "4111111111111111"
},
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"address1": "12345 Example Way",
"city": "Atlanta",
"state": "GA",
"zip": "30301",
"country": "USA",
"shipping_address1": "12345 Example Way",
"shipping_city": "Atlanta",
"shipping_state": "GA",
"shipping_zip": "30301",
"shipping_country": "USA"
}
}
<payment_method>
<apple_pay>
<payment_data>
<![CDATA[{"version":"EC_v1","data":"QlzLxRFnNP9/GTaMhBwgmZ2ywntbr9iOcBY4TjPZyNrnCwsJd2cq61bDQjo3agVU0LuEot2VIHHocVrp5jdy0FkxdFhGd+j7hPvutFYGwZPcuuBgROb0beA1wfGDi09I+OWL+8x5+8QPl+y8EAGJdWHXr4CuL7hEj4CjtUhfj5GYLMceUcvwgGaWY7WzqnEO9UwUowlDP9C3cD21cW8osn/IKROTInGcZB0mzM5bVHM73NSFiFepNL6rQtomp034C+p9mikB4nc+vR49oVop0Pf+uO7YVq7cIWrrpgMG7ussnc3u4bmr3JhCNtKZzRQ2MqTxKv/CfDq099JQIvTj8hbqswv1t+yQ5ZhJ3m4bcPwrcyIVej5J241R7dNPu9xVjM6LSOX9KeGZQGud","signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTUwMjI0MTgzNTU5WjAvBgkqhkiG9w0BCQQxIgQgohbm8d0A42OAyMnc5fsgQoCNYjtEd/W/dW6+yezIwoAwCgYIKoZIzj0EAwIERzBFAiEAtEkap+JHypwfL1EdabD7RWPZol3na0LhMk9XzLhis0oCIGwxzOhQnMw+Td8WglTMNYcidqeYILTGzn3zMEXmW3j7AAAAAAAA","header":{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQwjaSlnZ3EXpwKfWAd2e1VnbS6vmioMyF6bNcq/Qd65NLQsjrPatzHWbJzG7v5vJtAyrf6WhoNx3C1VchQxYuw==","transactionId":"e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371","publicKeyHash":"/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI="}}
]]>
</payment_data>
<test_card_number>4111111111111111</test_card_number>
</apple_pay>
<email>joey@example.com</email>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<first_name>Joey</first_name>
<last_name>Smith</last_name>
<address1>12345 Example Way</address1>
<city>Atlanta</city>
<state>GA</state>
<zip>30301</zip>
<country>USA</country>
<shipping_address1>12345 Example Way</shipping_address1>
<shipping_city>Atlanta</shipping_city>
<shipping_state>GA</shipping_state>
<shipping_zip>30301</shipping_zip>
<shipping_country>USA</shipping_country>
</payment_method>
HTTPS/1.1 201 Created
{
"transaction": {
"token": "T6uE4YJ1Pztb3C2h0n3azd8im3M",
"created_at": "2018-11-06T20:10:47Z",
"updated_at": "2018-11-06T20:10:47Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "HgMCAtQCjZtxuDBC6fqabmvZIAq",
"created_at": "2018-11-06T20:10:47Z",
"updated_at": "2018-11-06T20:10:47Z",
"email": "john.smith@example.com",
"data": null,
"storage_state": "cached",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "John",
"last_name": "Smith",
"month": 12,
"year": 2023,
"full_name": "John Smith",
"address1": "12345 Example Way",
"address2": null,
"city": "Atlanta",
"state": "GA",
"zip": "30301",
"country": "USA",
"phone_number": null,
"company": null,
"shipping_address1": "12345 Example Way",
"shipping_address2": null,
"shipping_city": "Atlanta",
"shipping_state": "GA",
"shipping_zip": "30301",
"shipping_country": "USA",
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "apple_pay",
"errors": [
]
}
}
}
<transaction>
<token>5tozGHP1EGxrVKpHTD2y6ZmJvST</token>
<created_at type="dateTime">2018-11-06T20:10:46Z</created_at>
<updated_at type="dateTime">2018-11-06T20:10:47Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>8CkRPxdrA3dbvapFrSiPZuXZ4dL</token>
<created_at type="dateTime">2018-11-06T20:10:46Z</created_at>
<updated_at type="dateTime">2018-11-06T20:10:47Z</updated_at>
<email>joey@example.com</email>
<data nil="true"></data>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joey</first_name>
<last_name>Smith</last_name>
<month type="integer">12</month>
<year type="integer">2023</year>
<full_name>Joey Smith</full_name>
<address1>12345 Example Way</address1>
<address2 nil="true"></address2>
<city>Atlanta</city>
<state>GA</state>
<zip>30301</zip>
<country>USA</country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<shipping_address1>12345 Example Way</shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city>Atlanta</shipping_city>
<shipping_state>GA</shipping_state>
<shipping_zip>30301</shipping_zip>
<shipping_country>USA</shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>apple_pay</payment_method_type>
<errors>
</errors>
</payment_method>
</transaction>
Add an Apple Pay payment method to the authenticated environment’s vault.
To create a test Apple Pay payment method, set the test_card_number element to one of the known test credit card numbers. For more information about testing on Spreedly, please see this guide.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ apple_pay | Apple pay element |
| ❯❯ payment_data required |
The JSON serialized paymentData property of an Apple Pay PKPaymentToken |
| ❯❯ test_card_number | Apple Pay does not provide a way to create a test payment token. To mark this as a test Apple Pay payment method, specify a test card number in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Apple Pay payment data. |
| ❯ retained | true if this payment method should be automatically retained on creation |
| The email address of the cardholder | |
| ❯ first_name | The first name of the cardholder |
| ❯ last_name | The last name of the cardholder |
| ❯ address1 | Cardholder’s address, line 1 |
| ❯ address2 | Cardholder’s address, line 2 |
| ❯ city | Cardholder’s city |
| ❯ state | Cardholder’s state |
| ❯ zip | Cardholder’s zip |
| ❯ country | Cardholder’s country |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
Response Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction (not the created payment method) at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ retained | if the payment method was set to be automatically retained on creation |
| ❯ payment_method | The payment method created as part of this transaction |
| ❯❯ token | The token identifying the newly created payment method in the Spreedly vault |
| ❯❯ storage_state | The storage state of the payment method |
| ❯❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, third_party_token, etc… |
| ❯❯ errors | If the payment method is invalid (missing required fields, etc…), there will be associated error messages here |
| ❯❯ last_four_digits | The last four digits of the (Apple Pay alias) credit card number. This can be displayed to the user. |
| ❯❯ first_six_digits | The first six digits of the (Apple Pay alias) credit card number. This can be displayed to the user. |
| ❯❯ issuer_identification_number | The numbers of the PAN required to identify the card issuer. |
| ❯❯ month | The expiration month |
| ❯❯ year | The expiration year |
Create Google Pay
POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"google_pay": {
"payment_data": {
"signature": "MEUCIA6SGVRwhOyeYRkeDUUNwB/kGtyfQAlOsg7NZydT17u/AiEA48BhWGQEF1EbEU0J+m8eSK3rTfhok9QqpiFVbME+Ky0=",
"protocolVersion": "ECv1",
"signedMessage": "{\"encryptedMessage\":\"3v4IcT/eovIDP2WF8iRUy4qWQnE9Cx0vQxIZ5f9i3Emv3Tzs1AzvB7cxXhxrjp9FVIzdOwsZAPAsm03gvoYq8Xdr70XvrVRd2MFwQhMC7IV/uEsthw4JsR8oCkbI5v/zqhu2B+JodFgavNliHcpKBgijy2D6bpx7jXEkM39M/L4oBObFxFrhVSLA1GjOV6A5gLAXNXt0ffkCYekihqAyJrWlk3sCBDCF5SUiAKEIOIZtzZLgusxjVp6ufZHOHm/53uhAi6JWSJ1E6G5aaYGtULYdwgURHtxN5OIzQPYlEGctaQd5tgfCsBFfGkYyN1GRNgclbaLzAfk/Jn7/6IVKuV0ol3xubTcnjGTZXwtTjiEyYDoz1yVqB9ViMmJa55L6nBtbbAkcNEgAi7dPnrbvBGEP7QWsNT9D71g8SWrlRTCYUAOyuamaQhofG4ul1IVjmltdAy2BHBWpqgJnR9kczydQyE7uDiqhSC1/0eG8GCGIqoi8XfOioGXfMyLZ1p2ZcNK9ECjzUrH/edrwgtShxgWuWMwQTM4DQlVTAA/R4DVs192YWZcc7jm5wLqZ0+XEaPuighJM1Ps1Egeccg\\u003d\\u003d\",\"ephemeralPublicKey\":\"BA2SvF9BdCX7Tl1wwRkyLzTfqhctobhZgSugC9Cz77XNUCBOBMfFyJQt506PUs89D6IJZZfOkZopy0shRF9Uph4\\u003d\",\"tag\":\"Uhin1BE7KAuuiam7eEQFimRUDd9Xn6tZc2fClTpfrXQ\\u003d\"}"
},
"first_name": "John",
"last_name": "Smith",
"test_card_number": "4111111111111111"
},
"email": "john.smith@example.com"
}
}
<payment_method>
<google_pay>
<payment_data>
<![CDATA[{"signature":"MEUCIA6SGVRwhOyeYRkeDUUNwB/kGtyfQAlOsg7NZydT17u/AiEA48BhWGQEF1EbEU0J+m8eSK3rTfhok9QqpiFVbME+Ky0\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"3v4IcT/eovIDP2WF8iRUy4qWQnE9Cx0vQxIZ5f9i3Emv3Tzs1AzvB7cxXhxrjp9FVIzdOwsZAPAsm03gvoYq8Xdr70XvrVRd2MFwQhMC7IV/uEsthw4JsR8oCkbI5v/zqhu2B+JodFgavNliHcpKBgijy2D6bpx7jXEkM39M/L4oBObFxFrhVSLA1GjOV6A5gLAXNXt0ffkCYekihqAyJrWlk3sCBDCF5SUiAKEIOIZtzZLgusxjVp6ufZHOHm/53uhAi6JWSJ1E6G5aaYGtULYdwgURHtxN5OIzQPYlEGctaQd5tgfCsBFfGkYyN1GRNgclbaLzAfk/Jn7/6IVKuV0ol3xubTcnjGTZXwtTjiEyYDoz1yVqB9ViMmJa55L6nBtbbAkcNEgAi7dPnrbvBGEP7QWsNT9D71g8SWrlRTCYUAOyuamaQhofG4ul1IVjmltdAy2BHBWpqgJnR9kczydQyE7uDiqhSC1/0eG8GCGIqoi8XfOioGXfMyLZ1p2ZcNK9ECjzUrH/edrwgtShxgWuWMwQTM4DQlVTAA/R4DVs192YWZcc7jm5wLqZ0+XEaPuighJM1Ps1Egeccg\\u003d\\u003d\",\"ephemeralPublicKey\":\"BA2SvF9BdCX7Tl1wwRkyLzTfqhctobhZgSugC9Cz77XNUCBOBMfFyJQt506PUs89D6IJZZfOkZopy0shRF9Uph4\\u003d\",\"tag\":\"Uhin1BE7KAuuiam7eEQFimRUDd9Xn6tZc2fClTpfrXQ\\u003d\"}"}
]]>
</payment_data>
<first_name>John</first_name>
<last_name>Smith</last_name>
<test_card_number>4111111111111111</test_card_number>
</google_pay>
<email>john.smith@example.com</email>
</payment_method>
HTTPS/1.1 201 Created
{
"transaction": {
"token": "1n4j3sExB12GFJcncZnPdZXMaXs",
"created_at": "2018-09-25T15:59:50Z",
"updated_at": "2018-09-25T15:59:50Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "2w9cGgCkg77AmZj8xFLNQnKPdSh",
"created_at": "2018-09-25T15:59:50Z",
"updated_at": "2018-09-25T15:59:50Z",
"email": "john.smith@example.com",
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "John",
"last_name": "Smith",
"month": 12,
"year": 2023,
"full_name": "John Smith",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "google_pay",
"google_pay_type": "TOKENIZED_CARD",
"errors": [
]
}
}
}
<transaction>
<token>9v92w2708YpQ5KYxsz62oZRlPsx</token>
<created_at type="dateTime">2018-09-25T15:59:50Z</created_at>
<updated_at type="dateTime">2018-09-25T15:59:50Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>UbOdSftBw7YlCG6BXB0szSGKwGZ</token>
<created_at type="dateTime">2018-09-25T15:59:50Z</created_at>
<updated_at type="dateTime">2018-09-25T15:59:50Z</updated_at>
<email>john.smith@example.com</email>
<data nil="true"></data>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"></metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>John</first_name>
<last_name>Smith</last_name>
<month type="integer">12</month>
<year type="integer">2023</year>
<full_name>John Smith</full_name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>google_pay</payment_method_type>
<google_pay_type>TOKENIZED_CARD</google_pay_type>
<errors>
</errors>
</payment_method>
</transaction>
Add an Google Pay payment method to the authenticated environment’s vault.
To create a test Google Pay payment method, set the test_card_number element to one of the known test credit card numbers. For more information about testing on Spreedly, please see this guide.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ Google_pay | Google pay element |
| ❯❯ payment_data required |
The JSON serialized paymentData |
| ❯❯ test_card_number | Specify a test card number in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Google Pay payment data. |
| ❯❯ first_name | The first name of the cardholder |
| ❯❯ last_name | The last name of the cardholder |
| ❯❯ address1 | Cardholder’s address, line 1 |
| ❯❯ address2 | Cardholder’s address, line 2 |
| ❯❯ city | Cardholder’s city |
| ❯❯ state | Cardholder’s state |
| ❯❯ zip | Cardholder’s zip |
| ❯❯ country | Cardholder’s country |
| ❯ retained | true if this payment method should be automatically retained on creation |
| The email address of the cardholder | |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
Response Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction (not the created payment method) at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ retained | if the payment method was set to be automatically retained on creation |
| ❯ payment_method | The payment method created as part of this transaction |
| ❯❯ token | The token identifying the newly created payment method in the Spreedly vault |
| ❯❯ storage_state | The storage state of the payment method |
| ❯❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, third_party_token, etc… |
| ❯❯ errors | If the payment method is invalid (missing required fields, etc…), there will be associated error messages here |
| ❯❯ last_four_digits | The last four digits of the (Google Pay alias) credit card number. This can be displayed to the user. |
| ❯❯ first_six_digits | The first six digits of the (Google Pay alias) credit card number. This can be displayed to the user. |
| ❯❯ issuer_identification_number | The numbers of the PAN required to identify the card issuer. |
| ❯❯ month | The expiration month |
| ❯❯ year | The expiration year |
Create third party token
POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"payment_method_type": "third_party_token",
"reference": "MF424cE3jPVESunRNZW0oFtmyI4",
"gateway_type": "litle"
}
}
<payment_method>
<payment_method_type>third_party_token</payment_method_type>
<reference>MF424cE3jPVESunRNZW0oFtmyI4</reference>
<gateway_type>litle</gateway_type>
</payment_method>
HTTPS/1.1 201 Created
{
"transaction": {
"token": "ActkD0upyjQvkvtER6ra7vdpZJQ",
"created_at": "2017-07-27T17:55:02Z",
"updated_at": "2017-07-27T17:55:02Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "8s5YC3RaRv3zfLVNmuzVep9Mo0z",
"created_at": "2017-07-27T17:55:02Z",
"updated_at": "2017-07-27T17:55:02Z",
"gateway_type": "litle",
"storage_state": "cached",
"third_party_token": "MF424cE3jPVESunRNZW0oFtmyI4",
"payment_method_type": "third_party_token",
"errors": [
]
}
}
}
<transaction>
<token>XLRFd2gmnEVAx7K3Ryme25dvlhU</token>
<created_at type="dateTime">2017-07-27T17:55:03Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:03Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>ZeA4EtYPFZ8Km9OlKkd3RWOFFQv</token>
<created_at type="dateTime">2017-07-27T17:55:03Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:03Z</updated_at>
<gateway_type>litle</gateway_type>
<storage_state>cached</storage_state>
<third_party_token>MF424cE3jPVESunRNZW0oFtmyI4</third_party_token>
<payment_method_type>third_party_token</payment_method_type>
<errors>
</errors>
</payment_method>
</transaction>
Add a third party token payment method to the authenticated environment’s vault.
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 about third party tokens, please see this guide.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ payment_method_type | third_party_token to represent an externally vaulted payment method reference |
| ❯ reference | The token identifying the payment method at the external gateway |
| ❯ gateway_type | The type of the external gateway |
Response Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction (not the created payment method) at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ retained | if the payment method was set to be automatically retained on creation |
| ❯ payment_method | The payment method created as part of this transaction |
| ❯❯ token | The token identifying the newly created payment method in the Spreedly vault |
| ❯❯ storage_state | The storage state of the payment method |
| ❯❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, third_party_token, etc… |
| ❯❯ errors | If the payment method is invalid (missing required fields, etc…), there will be associated error messages here |
| ❯❯ third_party_token | The token identifying the payment method at the external gateway |
| ❯❯ gateway_type | The type of the external gateway at which the target payment method is stored |
List
GET /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"payment_methods": [
{
"token": "72GW93Z3rarasS7EqiUCXsqx4jW",
"created_at": "2017-06-22T15:10:48Z",
"updated_at": "2017-06-22T15:10:48Z",
"gateway_type": "test",
"storage_state": "retained",
"third_party_token": "test_vault:4111111111111111",
"payment_method_type": "third_party_token",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
]
},
{
"token": "5voMXfW8xotx25P7OyNywmfeYPZ",
"created_at": "2017-06-22T15:10:49Z",
"updated_at": "2017-06-22T15:10:49Z",
"gateway_type": "test",
"storage_state": "retained",
"third_party_token": "test_vault:4111111111111111",
"payment_method_type": "third_party_token",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
]
}
]
}
<payment_methods>
<payment_method>
<token>72GW93Z3rarasS7EqiUCXsqx4jW</token>
<created_at type="dateTime">2017-06-22T15:10:48Z</created_at>
<updated_at type="dateTime">2017-06-22T15:10:48Z</updated_at>
<gateway_type>test</gateway_type>
<storage_state>retained</storage_state>
<third_party_token>test_vault:4111111111111111</third_party_token>
<payment_method_type>third_party_token</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
</payment_method>
<payment_method>
<token>5voMXfW8xotx25P7OyNywmfeYPZ</token>
<created_at type="dateTime">2017-06-22T15:10:49Z</created_at>
<updated_at type="dateTime">2017-06-22T15:10:49Z</updated_at>
<gateway_type>test</gateway_type>
<storage_state>retained</storage_state>
<third_party_token>test_vault:4111111111111111</third_party_token>
<payment_method_type>third_party_token</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
</payment_method>
</payment_methods>
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.
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
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
| metadata | A metadata key/value pair represented as a hash (e.g. metadata[key]=value). |
| state | The list of storage_states to return. By default returns retained, acceptable values are retained, redacted, cached, used, closed |
| count | The number of payment methods to return. By default returns 20, maximum allowed is 100. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| payment_methods | Root element |
| ❯ token | The token uniquely identifying the payment method at Spreedly |
| ❯ retained | if the payment method was set to be automatically retained on creation |
| ❯ storage_state | The storage state of the payment method |
| ❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, etc… |
| ❯ errors | If the payment method is invalid (missing first name, number etc…), there will be an associated error message here |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Show
GET /v1/payment_methods/<payment_method_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2022-04-14T18:46:01Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "String Value",
"another_key": "123",
"final_key": "true"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2022-04-14T18:46:01Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
Get a payment method with the given token.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ token | The token identifying the newly created payment method in the Spreedly vault |
| ❯ storage_state | The storage state of the payment method |
| ❯ test | true if this payment method is a test payment method and cannot be used against real gateways or receivers |
| ❯ payment_method_type | The type of this payment method, e.g., credit_card, bank_account, apple_pay, google_pay, third_party_token, etc… |
| ❯ errors | If the payment method is invalid (missing required fields, etc…), there will be associated error messages here |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Update
PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"first_name": "Newfirst",
"last_name": "Newlast",
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
}
}
}
<payment_method>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
</payment_method>
HTTPS/1.1 200 OK
{
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2022-04-14T18:46:01Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2023-06-05T02:33:54Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
<stored_credential_usage>
<test>
<original_network_transaction_id>37be5367d6dbe4a88c9d</original_network_transaction_id>
<network_transaction_id>37be5367d6dbe4a88c9d</network_transaction_id>
</test>
</stored_credential_usage>
</payment_method>
Update a payment method’s non-sensitive attributes.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ attribute | One or more non-sensitive attributes to update. Non-sensitive attributes are attributes excluding card numbers, verification values (CVV), bank account numbers etc… |
| ❯ allow_blank_name | true if this payment method should skip the name validation requirement (credit card only) |
| ❯ allow_expired_date | true if this payment method should skip the expired date validation requirement (credit card only) |
| ❯ allow_blank_date | true if this payment method should skip the expiration date validation requirement |
| ❯ eligible_for_card_updater | true if this payment method should be included in Account Updater |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ token | The token uniquely identifying the updated payment method |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
update_gratis
PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/update_gratis.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"managed": true
}
}
<payment_method>
<managed>true</managed>
</payment_method>
HTTPS/1.1 200 OK
{
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2023-07-14T18:05:20Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"stored_credential_usage": {
"test": {
"original_network_transaction_id": "37be5367d6dbe4a88c9d",
"network_transaction_id": "37be5367d6dbe4a88c9d"
}
},
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2023-07-14T18:05:19Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
<stored_credential_usage>
<test>
<original_network_transaction_id>37be5367d6dbe4a88c9d</original_network_transaction_id>
<network_transaction_id>37be5367d6dbe4a88c9d</network_transaction_id>
</test>
</stored_credential_usage>
</payment_method>
Update a payment method’s management state. For further details, see Advanced Vault.
Please note, that this API call is only available to merchants who are currently enrolled in Advanced Vault.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ managed | true or false |
| ❯ allow_blank_name | true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date | true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date | true if this payment method should skip the expiration date validation requirement |
| ❯ eligible_for_card_updater | true if this payment method should be included in Account Updater |
Response Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ token | The token uniquely identifying the updated payment method |
| ❯ managed | The value indicating the payment method’s management status |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Delete metadata
DELETE /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/metadata.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"keys": [
"another_key",
"final_key"
]
}
<keys type="array">
<value>another_key</value>
<value>final_key</value>
</keys>
HTTPS/1.1 200 OK
{
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2018-11-07T20:42:14Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2018-11-07T20:47:26Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
Remove key value pairs from a payment method’s metadata.
URL Parameters
| Parameter | Description |
|---|---|
| keys | An array of metadata key whose key/value pairs will be deleted. If a metadata key does not already exist, it will be ignored. |
Retain
PUT /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/retain.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"transaction": {
"token": "4IaiFmcDuB4gr1hfEukGit1MuJl",
"created_at": "2022-04-15T11:26:15Z",
"updated_at": "2022-04-15T11:26:15Z",
"succeeded": true,
"transaction_type": "RetainPaymentMethod",
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2022-04-15T11:26:15Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "String Value",
"another_key": "123",
"final_key": "true"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<token>HEDkJEeVxxfh52d1NMw8iSWFMDU</token>
<created_at type="dateTime">2022-04-15T11:26:15Z</created_at>
<updated_at type="dateTime">2022-04-15T11:26:15Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>RetainPaymentMethod</transaction_type>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:26:15Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Retain (keep in the Spreedly vault for future use) a payment method.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ payment_method | The payment method that was retained |
| ❯❯ storage_state | The new state of the payment method (retained) |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Store
POST /v1/gateways/<gateway_token>/store.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"created_at": "2022-04-15T11:26:15Z",
"currency_code": null,
"updated_at": "2022-04-15T11:26:15Z",
"succeeded": true,
"token": "JCdsxQyvgkOAzJkmx5C7PLJeiAO",
"state": "succeeded",
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"transaction_type": "Store",
"third_party_token": null,
"gateway_transaction_id": "62",
"gateway_latency_ms": 11,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"sub_merchant_key": null,
"payment_method": {
"token": "SEeYT1k54yYeXJyYjeYAujWn9lt",
"created_at": "2022-04-15T11:26:15Z",
"updated_at": "2022-04-15T11:26:15Z",
"gateway_type": "test",
"storage_state": "retained",
"metadata": null,
"third_party_token": "test_vault:4111111111111111",
"payment_method_type": "third_party_token",
"errors": [
]
},
"basis_payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2022-04-15T11:26:15Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "String Value",
"another_key": "123",
"final_key": "true"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
},
"response": {
"success": true,
"message": "Successful store",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2022-04-15T11:26:15Z",
"updated_at": "2022-04-15T11:26:15Z"
}
}
}
<transaction>
<created_at type="dateTime">2022-04-15T11:26:15Z</created_at>
<currency_code nil="true"/>
<updated_at type="dateTime">2022-04-15T11:26:15Z</updated_at>
<succeeded type="boolean">true</succeeded>
<token>7E9aTI6KrHgnjDfUC3177qZBAqB</token>
<state>succeeded</state>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<transaction_type>Store</transaction_type>
<third_party_token nil="true"/>
<gateway_transaction_id>52</gateway_transaction_id>
<gateway_latency_ms type="integer">9</gateway_latency_ms>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<sub_merchant_key nil="true"/>
<payment_method>
<token>PzbfgpmaMfoXrnPG2FVCZN8CSPw</token>
<created_at type="dateTime">2022-04-15T11:26:15Z</created_at>
<updated_at type="dateTime">2022-04-15T11:26:15Z</updated_at>
<gateway_type>test</gateway_type>
<storage_state>retained</storage_state>
<metadata nil="true"/>
<third_party_token>test_vault:4111111111111111</third_party_token>
<payment_method_type>third_party_token</payment_method_type>
<errors>
</errors>
</payment_method>
<basis_payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:26:15Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</basis_payment_method>
<response>
<success type="boolean">true</success>
<message>Successful store</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2022-04-15T11:26:15Z</created_at>
<updated_at type="dateTime">2022-04-15T11:26:15Z</updated_at>
</response>
</transaction>
Tokenize a payment method at the gateway.
This transaction copies the payment method information from the Spreedly vault to the gateway’s vault 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.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ payment_method_token required |
The token of the payment method to copy to the gateway |
| ❯ currency_code | The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. Some gateways may need this for a store call but most do not. |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions. |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause. |
| ❯ payment_method | The Spreedly payment method token that references the payment method stored at the gateway |
| ❯❯ third_party_token | The token identifying the payment method as it exists at the gateway |
| ❯ basis_payment_method | The payment method vaulted at Spreedly that was copied to the gateway as part of this transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Redact
PUT /v1/payment_methods/<payment_method_token>/redact.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": false,
"created_at": "2022-04-15T11:25:39Z",
"updated_at": "2022-04-15T11:25:39Z",
"succeeded": true,
"token": "6TW5FroKua8CaebJUMcEiXzxPBj",
"state": "succeeded",
"gateway_specific_fields": {
},
"gateway_specific_response_fields": {
},
"transaction_type": "RedactPaymentMethod",
"order_id": null,
"ip": null,
"gateway_transaction_id": null,
"gateway_latency_ms": null,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "NNgAp50f3BASpah2NLovmIMQDuE",
"created_at": "2022-04-14T18:15:18Z",
"updated_at": "2022-04-15T11:25:39Z",
"email": "joey@example.com",
"data": null,
"storage_state": "redacted",
"test": true,
"metadata": {
"key": "String Value",
"another_key": "123",
"final_key": "true"
},
"callback_url": null,
"last_four_digits": "4444",
"first_six_digits": "555555",
"card_type": "master",
"first_name": "Joey",
"last_name": "Jones",
"month": 3,
"year": 2029,
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313",
"company": "Acme Inc.",
"full_name": "Joey Jones",
"eligible_for_card_updater": true,
"shipping_address1": "33 Lane Road",
"shipping_address2": "Apartment 4",
"shipping_city": "Wanaque",
"shipping_state": "NJ",
"shipping_zip": "31331",
"shipping_country": "US",
"shipping_phone_number": "919.331.3313",
"issuer_identification_number": "55555555",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "b5fe350d5135ab64a8f3c1097fadefd9effb",
"verification_value": "",
"number": ""
}
}
}
<transaction>
<on_test_gateway type="boolean">false</on_test_gateway>
<created_at type="dateTime">2022-04-15T11:25:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:25:38Z</updated_at>
<succeeded type="boolean">true</succeeded>
<token>WdtgsGYLqq6BsybRX4Nqfmmj66n</token>
<state>succeeded</state>
<gateway_specific_fields>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<transaction_type>RedactPaymentMethod</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<gateway_transaction_id nil="true"></gateway_transaction_id>
<gateway_latency_ms nil="true"></gateway_latency_ms>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>NNgAp50f3BASpah2NLovmIMQDuE</token>
<created_at type="dateTime">2022-04-14T18:15:18Z</created_at>
<updated_at type="dateTime">2022-04-15T11:25:38Z</updated_at>
<email>joey@example.com</email>
<data nil="true"></data>
<storage_state>redacted</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>4444</last_four_digits>
<first_six_digits>555555</first_six_digits>
<card_type>master</card_type>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<month type="integer">3</month>
<year type="integer">2029</year>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
<company>Acme Inc.</company>
<full_name>Joey Jones</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1>33 Lane Road</shipping_address1>
<shipping_address2>Apartment 4</shipping_address2>
<shipping_city>Wanaque</shipping_city>
<shipping_state>NJ</shipping_state>
<shipping_zip>31331</shipping_zip>
<shipping_country>US</shipping_country>
<shipping_phone_number>919.331.3313</shipping_phone_number>
<issuer_identification_number>55555555</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number></number>
<fingerprint>b5fe350d5135ab64a8f3c1097fadefd9effb</fingerprint>
</payment_method>
</transaction>
Redact (strip of any sensitive credentials and make inactive) a payment method.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ remove_from_gateway | If the payment method is also stored at the gateway (e.g., for third party vaulting or offsite authorizations), include the token of the gateway here and it will be removed from the gateway as well as being redacted from Spreedly. This element is optional. If required, gateway_specific_fields can be used in tandem with remove_from_gateway. See your gateways guide for gateway specific field options and formatting. |
| ❯ remove_personal_data | true if personally identifiable information should be removed from the payment method and related its transactions. This element is optional. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ personal_data_removal | Personal data redaction information as part of this transaction, if applicable. |
| ❯ payment_method | The payment method that was redacted |
| ❯❯ storage_state | The new state of the payment method (redacted) |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Recache
POST /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/recache.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"credit_card": {
"verification_value": "423"
}
}
}
<payment_method>
<credit_card>
<verification_value>423</verification_value>
</credit_card>
</payment_method>
HTTPS/1.1 200 OK
{
"transaction": {
"token": "1W7ydsgjmXa9pI7uX4kkD3bOS7f",
"transaction_type": "RecacheSensitiveData",
"succeeded": true,
"data": null,
"created_at": "2022-04-15T11:25:38Z",
"updated_at": "2022-04-15T11:25:38Z",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2022-04-15T11:25:38Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "String Value",
"another_key": "123",
"final_key": "true"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<token>Ni8rpmqfrbT1T1ss0Bew0WsnpUs</token>
<transaction_type>RecacheSensitiveData</transaction_type>
<succeeded type="boolean">true</succeeded>
<message key="messages.transaction_succeeded">Succeeded!</message>
<data nil="true"></data>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:25:38Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<created_at type="dateTime">2022-04-15T11:25:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:25:38Z</updated_at>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| payment_method | Root element |
| ❯ credit_card | Credit card element |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
Response Body
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction (not the payment method) at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ payment_method | The payment method whose CVV was updated |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Transactions
GET /v1/payment_methods/56wyNnSmuA6CWYP7w0MiYCVIbW6/transactions.<format>?order=desc HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"transactions": [
{
"token": "Ni8rpmqfrbT1T1ss0Bew0WsnpUs",
"transaction_type": "RecacheSensitiveData",
"succeeded": true,
"data": null,
"created_at": "2022-04-15T11:25:38Z",
"updated_at": "2022-04-15T11:25:38Z",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2022-04-15T11:25:38Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "String Value",
"another_key": "123",
"final_key": "true"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
]
}
<transactions>
<transaction>
<token>Ni8rpmqfrbT1T1ss0Bew0WsnpUs</token>
<transaction_type>RecacheSensitiveData</transaction_type>
<succeeded type="boolean">true</succeeded>
<message key="messages.transaction_succeeded">Succeeded!</message>
<data nil="true"></data>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:25:38Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<created_at type="dateTime">2022-04-15T11:25:38Z</created_at>
<updated_at type="dateTime">2022-04-15T11:25:38Z</updated_at>
</transaction>
</transactions>
Get an ordered and paginated list of transactions executed against a specific payment method.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method whose transactions should be fetched |
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Certificates
List certificates
GET /v1/certificates.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"certificates": [
{
"token": "8ERbJicjPjc2p8OfDnSZXbFHDdp",
"algorithm": "ec-prime256v1",
"cn": "MyApp ApplePay Production Certificate",
"o": null,
"ou": null,
"c": null,
"st": null,
"l": null,
"email_address": "security@yourorg.com",
"public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYKXdTdWUxdSjgHVN6uRUEjExXvE5\n7hPhu9BuQTuBDaQCdIhsDXj+aTaJL73BAQI8asKhcZynfcSIHJCoz0Xthg==\n-----END PUBLIC KEY-----\n",
"public_key_hash": "K3xhhI8Efg1/oVezCy2/r5EbC3MhrNTijO2sDo3YMaE=",
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBSDCB7wIBADCBjDEuMCwGA1UEAwwlTXlBcHAgQXBwbGVQYXkgUHJvZHVjdGlv\nbiBDZXJ0aWZpY2F0ZTEJMAcGA1UECgwAMQkwBwYDVQQLDAAxCTAHBgNVBAYTADEJ\nMAcGA1UECAwAMQkwBwYDVQQHDAAxIzAhBgkqhkiG9w0BCQEWFHNlY3VyaXR5QHlv\ndXJvcmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYKXdTdWUxdSjgHVN\n6uRUEjExXvE57hPhu9BuQTuBDaQCdIhsDXj+aTaJL73BAQI8asKhcZynfcSIHJCo\nz0XthqAAMAoGCCqGSM49BAMCA0gAMEUCIQDiwBI8XLAzt/23h7PIMSnPR71EoSyi\nr8ivSDzwW1bGdAIgQ3MH5fbtU9XFckDizWko+4Yvuy0OKDifYKp0c0qjP8c=\n-----END CERTIFICATE REQUEST-----\n",
"pem": null,
"created_at": "2017-06-22T20:42:05Z",
"updated_at": "2017-06-22T20:42:05Z"
},
{
"token": "J1Conxz9vbU8RBzj3Z1jMKaquwS",
"algorithm": "ec-prime256v1",
"cn": "MyApp ApplePay Production Certificate",
"o": null,
"ou": null,
"c": null,
"st": null,
"l": null,
"email_address": "security@yourorg.com",
"public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwueSZR2V+2bSdjuok5GNDPjfseuU\nBkTFmAvHns5LKjOnLHI9cE1zJYOn6Lvc3mAoQoCawO/M0pJQuOd+uqco7w==\n-----END PUBLIC KEY-----\n",
"public_key_hash": "lXtoHJvMFdmRq/N7Hm8UFnNr+9jJcdtYSWNfDLsMYzk=",
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBSTCB7wIBADCBjDEuMCwGA1UEAwwlTXlBcHAgQXBwbGVQYXkgUHJvZHVjdGlv\nbiBDZXJ0aWZpY2F0ZTEJMAcGA1UECgwAMQkwBwYDVQQLDAAxCTAHBgNVBAYTADEJ\nMAcGA1UECAwAMQkwBwYDVQQHDAAxIzAhBgkqhkiG9w0BCQEWFHNlY3VyaXR5QHlv\ndXJvcmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwueSZR2V+2bSdjuo\nk5GNDPjfseuUBkTFmAvHns5LKjOnLHI9cE1zJYOn6Lvc3mAoQoCawO/M0pJQuOd+\nuqco76AAMAoGCCqGSM49BAMCA0kAMEYCIQDiyLXI8RqeQJCSoM80IR0uKhtjHPFz\n4YrBZmA9E+GoeAIhAJFL7zUT/Xo/e1o5TBKJKamtG6hSAF8amP+96/LXymly\n-----END CERTIFICATE REQUEST-----\n",
"pem": null,
"created_at": "2017-06-22T21:24:27Z",
"updated_at": "2017-06-22T21:24:27Z"
}
]
}
<certificates>
<certificate>
<token>0304N680YM9WSAZKDA54GE9HXA</token>
<algorithm nil="true"></algorithm>
<cn>MyApp XML Signature Production Certificate</cn>
<o nil="true"></o>
<ou nil="true"></ou>
<c nil="true"></c>
<st nil="true"></st>
<l nil="true"></l>
<email_address>security@yourorg.com</email_address>
<public_key>-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV1sJK9aNE76M4H2k5t5
HNVTdCqmxFMf1HDufcueK49t1sj3wG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDg
IiJKIz+KwxeF1q+0it2cutxURjWY4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyf
xoBdlATrlMI70Gcgqmv5Xh7D+CR65ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfji
fno1f2W6Lj6euxvwiapaMTZioHe8uH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuev
fp6odCkAC69AIvttPEfqGcqNn+F0fLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKr
fwIDAQAB
-----END PUBLIC KEY-----
</public_key>
<public_key_hash>dnb3kyfglEbIgOB5wK6VfggYZFNU1q1Ms7sJn/6cjRc=</public_key_hash>
<csr nil="true"></csr>
<pem>-----BEGIN CERTIFICATE-----
MIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN
eUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq
hkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX
DTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ
cm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5
b3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv
WjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk
CJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4
V9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli
Q/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi
0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5
sPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4
3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW
NcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG
s+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX
HXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p
HDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R
jn30kQ==
-----END CERTIFICATE-----
</pem>
<created_at type="dateTime">2023-06-06T16:19:47Z</created_at>
<updated_at type="dateTime">2023-06-06T16:19:47Z</updated_at>
</certificate>
<certificate>
<token>04MBTRKHZW9V2THG1EFQGCWXHR</token>
<algorithm nil="true"></algorithm>
<cn>MyApp XML Signature Production Certificate</cn>
<o nil="true"></o>
<ou nil="true"></ou>
<c nil="true"></c>
<st nil="true"></st>
<l nil="true"></l>
<email_address>security@yourorg.com</email_address>
<public_key>-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV1sJK9aNE76M4H2k5t5
HNVTdCqmxFMf1HDufcueK49t1sj3wG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDg
IiJKIz+KwxeF1q+0it2cutxURjWY4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyf
xoBdlATrlMI70Gcgqmv5Xh7D+CR65ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfji
fno1f2W6Lj6euxvwiapaMTZioHe8uH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuev
fp6odCkAC69AIvttPEfqGcqNn+F0fLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKr
fwIDAQAB
-----END PUBLIC KEY-----
</public_key>
<public_key_hash>dnb3kyfglEbIgOB5wK6VfggYZFNU1q1Ms7sJn/6cjRc=</public_key_hash>
<csr nil="true"></csr>
<pem>-----BEGIN CERTIFICATE-----
MIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN
eUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq
hkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX
DTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ
cm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5
b3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv
WjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk
CJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4
V9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli
Q/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi
0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5
sPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4
3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW
NcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG
s+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX
HXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p
HDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R
jn30kQ==
-----END CERTIFICATE-----
</pem>
<created_at type="dateTime">2023-06-06T15:53:21Z</created_at>
<updated_at type="dateTime">2023-06-06T15:53:21Z</updated_at>
</certificate>
</certificates>
Retrieve an ordered and paginated list of all certificates in the authenticated environment.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| certificates | Root element |
| ❯ algorithm | The encryption algorithm used to create the key pair |
| ❯ cn | The certificate common name |
| ❯ o | The organization |
| ❯ ou | The organization unit |
| ❯ c | The country |
| ❯ st | The state |
| ❯ l | The locality or city |
| ❯ email_address | The email address |
| ❯ public_key | PEM-formatted public key value |
| ❯ public_key_hash | The base64 encoded, SHA256 hash, of the public key |
| ❯ csr | PEM formatted certificate signing request (CSR) |
| ❯ pem | The signed certificate in PEM format, if it has been set on this certificate |
Create certificate
POST /v1/certificates.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"certificate": {
"pem": "-----BEGIN CERTIFICATE-----\nMIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN\neUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq\nhkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX\nDTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ\ncm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5\nb3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv\nWjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk\nCJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4\nV9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli\nQ/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi\n0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5\nsPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4\n3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW\nNcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG\ns+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX\nHXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p\nHDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R\njn30kQ==\n-----END CERTIFICATE-----\n",
"private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAyV1sJK9aNE76M4H2k5t5HNVTdCqmxFMf1HDufcueK49t1sj3\nwG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDgIiJKIz+KwxeF1q+0it2cutxURjWY\n4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyfxoBdlATrlMI70Gcgqmv5Xh7D+CR6\n5ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfjifno1f2W6Lj6euxvwiapaMTZioHe8\nuH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuevfp6odCkAC69AIvttPEfqGcqNn+F0\nfLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKrfwIDAQABAoIBAQCAUYNPoVrHSKjS\nV/hsub+lKyAiP+fD5gC7nTetfCsQMTdajviqbZUZ8JBbWKVaWY/TjXB4zY9YXVng\nKVMTnd4GgnliGuTvS7cjRxazA2QUA8HEd/U0k85tkpryP1+72sl/XbE7ZSE533E4\ng2hd4CUlFroLUFNbmacKOB2t3F6tpaXZD3TXGd2QIWEdRVbBHcbH5ZLhOVlvyJ5k\n+gHXvpdVsZnmC8eZPPs/JL3B0SwJop8Ln+DKkg6P4s+oq9dkR0OwuhuE+iWV8evF\nLFb0j87kJV8JsHMvk3qbbunWHisQr23U4Vl/k6rjkodryrzDrwQ3czzR3nlKN/Kl\nVROR8TMBAoGBAOmi434+RbZQP9PdVEa+pEh2IA81L3og6+TqemL4sZtqlCEfrOZD\nFsSH6CEU13SMn7l+riYCzBYSdvPDAynhJp+u0REUQFPJAMcgefxw2mfJwFrtn9Ap\nJWaAPhcMeK8l/5rdZxnjECDRAkW+5SdtYj9x6rjgsmJ89DFdd5EW1JL/AoGBANyj\nvpNSRBdy+lM62T0DiAJ6gc0HpYQpNzIydIT9bh8zkmwU5z0pVtczpmIzdK0lPlHO\nERWgBXXsfRfEupVoFND9H5A7tTMQtJF4rLg3gUpa2alTUXSWfm9uS7TWVRYR7hsV\n/ui7oW3zIXdD8dRHozITSzM27gfiMy6Q3I/SIGeBAoGAf0lgObJBlq8n5wxpUtWg\neV3p338xa48uFZxtqygk0zCAnX89WoHokJAeto89RuEqUAwlYs4ZVFkg93MicRma\nSlsayfxHg545z0LxUshFJVB0fNWDQQx5tNtfeH0x7vJ7zGqdNixP6CEW5Nq4y/87\nDKfKoojAhwnenFp4vtI6ZA8CgYBqTvcvEo8+YSbd3Vf4fvAUiaRq/okwgY9Xv1nH\nDjj2Dao6K2QzYuy1qew8GqDYID7Dua8fpUecRwMK5b4k6M5G1/9SRoKLBTyLbwKB\njDTed6GyZTO1IiHvXMxbaH38sUzxfgqhZm5khKYWSgWGC7JFGWi9V3UfFU0l3aR4\nI317gQKBgQCxWrKZlfq/iWcvBqB8Ep4wiJPXZXjl/Dvic/2pCC69MMimtDTHQ8o8\ngp7c3Fp+RDO8U5wgqq2amodR1RPbAdgG7rQvewnzPsaTIKSfOueY3LG4UR22tNvZ\nLeaSV7WUssler/Ybk6Gj+psx8RXbL+ZcYPoeL7mb6kUoWFfzcmpIjA==\n-----END RSA PRIVATE KEY-----\n"
}
}
<certificate>
<pem>-----BEGIN CERTIFICATE-----
MIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN
eUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq
hkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX
DTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ
cm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5
b3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv
WjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk
CJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4
V9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli
Q/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi
0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5
sPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4
3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW
NcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG
s+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX
HXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p
HDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R
jn30kQ==
-----END CERTIFICATE-----
</pem>
<private_key>-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAyV1sJK9aNE76M4H2k5t5HNVTdCqmxFMf1HDufcueK49t1sj3
wG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDgIiJKIz+KwxeF1q+0it2cutxURjWY
4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyfxoBdlATrlMI70Gcgqmv5Xh7D+CR6
5ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfjifno1f2W6Lj6euxvwiapaMTZioHe8
uH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuevfp6odCkAC69AIvttPEfqGcqNn+F0
fLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKrfwIDAQABAoIBAQCAUYNPoVrHSKjS
V/hsub+lKyAiP+fD5gC7nTetfCsQMTdajviqbZUZ8JBbWKVaWY/TjXB4zY9YXVng
KVMTnd4GgnliGuTvS7cjRxazA2QUA8HEd/U0k85tkpryP1+72sl/XbE7ZSE533E4
g2hd4CUlFroLUFNbmacKOB2t3F6tpaXZD3TXGd2QIWEdRVbBHcbH5ZLhOVlvyJ5k
+gHXvpdVsZnmC8eZPPs/JL3B0SwJop8Ln+DKkg6P4s+oq9dkR0OwuhuE+iWV8evF
LFb0j87kJV8JsHMvk3qbbunWHisQr23U4Vl/k6rjkodryrzDrwQ3czzR3nlKN/Kl
VROR8TMBAoGBAOmi434+RbZQP9PdVEa+pEh2IA81L3og6+TqemL4sZtqlCEfrOZD
FsSH6CEU13SMn7l+riYCzBYSdvPDAynhJp+u0REUQFPJAMcgefxw2mfJwFrtn9Ap
JWaAPhcMeK8l/5rdZxnjECDRAkW+5SdtYj9x6rjgsmJ89DFdd5EW1JL/AoGBANyj
vpNSRBdy+lM62T0DiAJ6gc0HpYQpNzIydIT9bh8zkmwU5z0pVtczpmIzdK0lPlHO
ERWgBXXsfRfEupVoFND9H5A7tTMQtJF4rLg3gUpa2alTUXSWfm9uS7TWVRYR7hsV
/ui7oW3zIXdD8dRHozITSzM27gfiMy6Q3I/SIGeBAoGAf0lgObJBlq8n5wxpUtWg
eV3p338xa48uFZxtqygk0zCAnX89WoHokJAeto89RuEqUAwlYs4ZVFkg93MicRma
SlsayfxHg545z0LxUshFJVB0fNWDQQx5tNtfeH0x7vJ7zGqdNixP6CEW5Nq4y/87
DKfKoojAhwnenFp4vtI6ZA8CgYBqTvcvEo8+YSbd3Vf4fvAUiaRq/okwgY9Xv1nH
Djj2Dao6K2QzYuy1qew8GqDYID7Dua8fpUecRwMK5b4k6M5G1/9SRoKLBTyLbwKB
jDTed6GyZTO1IiHvXMxbaH38sUzxfgqhZm5khKYWSgWGC7JFGWi9V3UfFU0l3aR4
I317gQKBgQCxWrKZlfq/iWcvBqB8Ep4wiJPXZXjl/Dvic/2pCC69MMimtDTHQ8o8
gp7c3Fp+RDO8U5wgqq2amodR1RPbAdgG7rQvewnzPsaTIKSfOueY3LG4UR22tNvZ
LeaSV7WUssler/Ybk6Gj+psx8RXbL+ZcYPoeL7mb6kUoWFfzcmpIjA==
-----END RSA PRIVATE KEY-----
</private_key>
</certificate>
HTTPS/1.1 201 Created
{
"certificate": {
"token": "VRYbo8zKRpCSTgMvfPuBOpeyN5n",
"algorithm": null,
"cn": "MyApp XML Signature Production Certificate",
"o": null,
"ou": null,
"c": null,
"st": null,
"l": null,
"email_address": "security@yourorg.com",
"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV1sJK9aNE76M4H2k5t5\nHNVTdCqmxFMf1HDufcueK49t1sj3wG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDg\nIiJKIz+KwxeF1q+0it2cutxURjWY4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyf\nxoBdlATrlMI70Gcgqmv5Xh7D+CR65ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfji\nfno1f2W6Lj6euxvwiapaMTZioHe8uH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuev\nfp6odCkAC69AIvttPEfqGcqNn+F0fLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKr\nfwIDAQAB\n-----END PUBLIC KEY-----\n",
"public_key_hash": "dnb3kyfglEbIgOB5wK6VfggYZFNU1q1Ms7sJn/6cjRc=",
"csr": null,
"pem": "-----BEGIN CERTIFICATE-----\nMIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN\neUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq\nhkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX\nDTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ\ncm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5\nb3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv\nWjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk\nCJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4\nV9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli\nQ/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi\n0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5\nsPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4\n3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW\nNcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG\ns+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX\nHXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p\nHDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R\njn30kQ==\n-----END CERTIFICATE-----\n",
"created_at": "2019-04-03T21:12:44Z",
"updated_at": "2019-04-03T21:12:44Z"
}
}
<certificate>
<token>L3N4RoaY9gb7mlctO4SoOQ7oa0u</token>
<algorithm nil="true"></algorithm>
<cn>MyApp XML Signature Production Certificate</cn>
<o nil="true"></o>
<ou nil="true"></ou>
<c nil="true"></c>
<st nil="true"></st>
<l nil="true"></l>
<email_address>security@yourorg.com</email_address>
<public_key>-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV1sJK9aNE76M4H2k5t5
HNVTdCqmxFMf1HDufcueK49t1sj3wG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDg
IiJKIz+KwxeF1q+0it2cutxURjWY4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyf
xoBdlATrlMI70Gcgqmv5Xh7D+CR65ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfji
fno1f2W6Lj6euxvwiapaMTZioHe8uH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuev
fp6odCkAC69AIvttPEfqGcqNn+F0fLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKr
fwIDAQAB
-----END PUBLIC KEY-----
</public_key>
<public_key_hash>dnb3kyfglEbIgOB5wK6VfggYZFNU1q1Ms7sJn/6cjRc=</public_key_hash>
<csr nil="true"></csr>
<pem>-----BEGIN CERTIFICATE-----
MIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN
eUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq
hkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX
DTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ
cm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5
b3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv
WjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk
CJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4
V9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli
Q/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi
0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5
sPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4
3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW
NcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG
s+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX
HXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p
HDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R
jn30kQ==
-----END CERTIFICATE-----
</pem>
<created_at type="dateTime">2019-04-03T21:12:43Z</created_at>
<updated_at type="dateTime">2019-04-03T21:12:43Z</updated_at>
</certificate>
Add a certificate to the authenticated environment for use in payment method distribution functions such as XML digital signatures.
Request Body
| Element | Description |
|---|---|
| certificate | Root element |
| ❯ pem required |
The signed certificate in PEM format |
| ❯ private_key | The certificate’s RSA or EC private key, in non-password-protected PEM format |
| ❯ level optional |
This is an optional parameter for organizational level certificate configuration; the value is set to environment by default but you can pass in organization for certificates shared across aunthenticated environments for the same organization. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| certificate | Root element |
| ❯ public_key | PEM-formatted public key of the certificate |
| ❯ public_key_hash | The base64 encoded, SHA256 hash, of the public key |
| ❯ csr | PEM formatted certificate signing request (CSR) |
| ❯ pem | The signed certificate in PEM format |
Generate certificate
POST /v1/certificates/generate.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"certificate": {
"algorithm": "ec-prime256v1",
"cn": "MyApp ApplePay Production Certificate",
"email_address": "security@yourorg.com"
}
}
<certificate>
<algorithm>ec-prime256v1</algorithm>
<cn>MyApp ApplePay Production Certificate</cn>
<email_address>security@yourorg.com</email_address>
</certificate>
HTTPS/1.1 201 Created
{
"certificate": {
"token": "65ZDETqI5decVMjVMyR5ckhaO9I",
"algorithm": "ec-prime256v1",
"cn": "MyApp ApplePay Production Certificate",
"o": null,
"ou": null,
"c": null,
"st": null,
"l": null,
"email_address": "security@yourorg.com",
"public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoQsY700wd1Vz8LzVDmH2ts4rYRRh\nk751oz+yW/2U2oe29yWrPJA5oLHZw8L7P8qmuyzuoFOjNxRlTypTyCFuag==\n-----END PUBLIC KEY-----\n",
"public_key_hash": "DkI5At7x9GHqoLfgANfHiL7/+S5CzxAmHOe09T6ubNg=",
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBSDCB7wIBADCBjDEuMCwGA1UEAwwlTXlBcHAgQXBwbGVQYXkgUHJvZHVjdGlv\nbiBDZXJ0aWZpY2F0ZTEJMAcGA1UECgwAMQkwBwYDVQQLDAAxCTAHBgNVBAYTADEJ\nMAcGA1UECAwAMQkwBwYDVQQHDAAxIzAhBgkqhkiG9w0BCQEWFHNlY3VyaXR5QHlv\ndXJvcmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoQsY700wd1Vz8LzV\nDmH2ts4rYRRhk751oz+yW/2U2oe29yWrPJA5oLHZw8L7P8qmuyzuoFOjNxRlTypT\nyCFuaqAAMAoGCCqGSM49BAMCA0gAMEUCIQDQgWnEgXLY45qGTqcwBOxvm8O5Qku+\nVPv3E+rX1J+oIQIgHK7KFPV2qb8D5WKP5LXG9Nla1Pw2cTCy0x7t8+4Kf7c=\n-----END CERTIFICATE REQUEST-----\n",
"pem": null,
"created_at": "2019-03-20T19:49:29Z",
"updated_at": "2019-03-20T19:49:29Z"
}
}
<certificate>
<token>XAJBkzmrXn4MjIzxpQ4KxVlULpi</token>
<algorithm>ec-prime256v1</algorithm>
<cn>MyApp ApplePay Production Certificate</cn>
<o nil="true"></o>
<ou nil="true"></ou>
<c nil="true"></c>
<st nil="true"></st>
<l nil="true"></l>
<email_address>security@yourorg.com</email_address>
<public_key>-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqkKCYmP9oiOErYBfHacG5TKUtW7h
H5GQW3Pr2mcxo+pHoxjIhKQj/OtUlP7EnfbSZipSOrai+3FmFc8CueUP4Q==
-----END PUBLIC KEY-----
</public_key>
<public_key_hash>ZWO9uQKXq69UnSQjE93slmfBFGmMzvKopcR9X2xR/ws=</public_key_hash>
<csr>-----BEGIN CERTIFICATE REQUEST-----
MIIBSDCB7wIBADCBjDEuMCwGA1UEAwwlTXlBcHAgQXBwbGVQYXkgUHJvZHVjdGlv
biBDZXJ0aWZpY2F0ZTEJMAcGA1UECgwAMQkwBwYDVQQLDAAxCTAHBgNVBAYTADEJ
MAcGA1UECAwAMQkwBwYDVQQHDAAxIzAhBgkqhkiG9w0BCQEWFHNlY3VyaXR5QHlv
dXJvcmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqkKCYmP9oiOErYBf
HacG5TKUtW7hH5GQW3Pr2mcxo+pHoxjIhKQj/OtUlP7EnfbSZipSOrai+3FmFc8C
ueUP4aAAMAoGCCqGSM49BAMCA0gAMEUCIFZPBNLZ1LyXU/COBYnXVMpe4xDKtIr6
/nDF+TH94r0hAiEAn4qwUb4q326hHsg6O2nflm97ZPUgY7yFrVHFfpDM24w=
-----END CERTIFICATE REQUEST-----
</csr>
<pem nil="true"></pem>
<created_at type="dateTime">2019-03-20T19:53:24Z</created_at>
<updated_at type="dateTime">2019-03-20T19:53:24Z</updated_at>
</certificate>
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.
Request Body
| Element | Description |
|---|---|
| certificate | Root element |
| ❯ algorithm required |
The encryption algorithm to use when creating the key pair. Currently, the only supported options are ec-prime256v1 representing the X9.62/SECG curve over a 256 bit prime field, or rsa-2048, which uses a 2048-bit RSA key. |
| ❯ cn required |
The certificate common name |
| ❯ o | The organization |
| ❯ ou | The organization unit |
| ❯ c | The country |
| ❯ st | The state |
| ❯ l | The locality or city |
| ❯ email_address | The email address |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| certificate | Root element |
| ❯ public_key | PEM-formatted public key of the certificate |
| ❯ public_key_hash | The base64 encoded, SHA256 hash, of the public key |
| ❯ csr | PEM formatted certificate signing request (CSR) |
| ❯ pem | The signed certificate in PEM format. This value will be empty on initial certificate generation. |
Update certificate
PUT /v1/certificates/<certificate_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"certificate": {
"pem": "-----BEGIN CERTIFICATE-----\nMIIEiTCCBC6gAwIBAgIIFRZ9ouKAzqwwCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMM\nK0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAk\nBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApB\ncHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNTAyMTkyMDMzMzBaFw0xNzAzMjAy\nMDMzMzBaMIG5MTowOAYKCZImiZPyLGQBAQwqbWVyY2hhbnQuY29tLnNlYXRnZWVr\nLlNwcmVlZGx5QXBwbGVQYXlUZXN0MUAwPgYDVQQDDDdNZXJjaGFudCBJRDogbWVy\nY2hhbnQuY29tLnNlYXRnZWVrLlNwcmVlZGx5QXBwbGVQYXlUZXN0MRMwEQYDVQQL\nDAo5QjNRWTlXQlo1MRcwFQYDVQQKDA5TZWF0R2VlaywgSW5jLjELMAkGA1UEBhMC\nVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQhoBD6FaOXUJq3e4EoI7rWemTz\nhLaPlAdF87WzmbhWKVNJ9LAEhrBjAtj6is765Ow2dnYta0QPF9EJoubwKOjKo4IC\nVTCCAlEwRwYIKwYBBQUHAQEEOzA5MDcGCCsGAQUFBzABhitodHRwOi8vb2NzcC5h\ncHBsZS5jb20vb2NzcDA0LWFwcGxld3dkcmNhMjAxMB0GA1UdDgQWBBQMV4lSAdev\nm6sv1MVm5yR0gWij+jAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFIS2hMw6hmJy\nFlmU6BqjvUjfOt8LMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4w\ngcMGCCsGAQUFBwICMIG2DIGzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBi\neSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHRhbmNlIG9mIHRoZSB0aGVuIGFwcGxp\nY2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMgb2YgdXNlLCBjZXJ0\naWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3RhdGVt\nZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmlj\nYXRlYXV0aG9yaXR5LzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmFwcGxl\nLmNvbS9hcHBsZXd3ZHJjYTIuY3JsMA4GA1UdDwEB/wQEAwIDKDBPBgkqhkiG92Nk\nBiAEQgxAODlDQjI1MDkxOTI0RDY3RjlFMEM2QUVDMzA0MENBMkFGNzA4MEYzRTBG\nQ0NFMTZBOTY5RDkyMUE0QkM5RTA1RjAKBggqhkjOPQQDAgNJADBGAiEAvKYdzDtD\nQ87guVNkybbcEY1Y/nXO9Ry+4fVDwXYMET0CIQDEiK1+xSSziPZ/PPQHF8MCWsD0\nLDW0aLigLHbDgQcrXA==\n-----END CERTIFICATE-----\n"
}
}
<certificate>
<pem>
<![CDATA[-----BEGIN CERTIFICATE-----
MIIEiTCCBC6gAwIBAgIIFRZ9ouKAzqwwCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMM
K0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAk
BgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApB
cHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNTAyMTkyMDMzMzBaFw0xNzAzMjAy
MDMzMzBaMIG5MTowOAYKCZImiZPyLGQBAQwqbWVyY2hhbnQuY29tLnNlYXRnZWVr
LlNwcmVlZGx5QXBwbGVQYXlUZXN0MUAwPgYDVQQDDDdNZXJjaGFudCBJRDogbWVy
Y2hhbnQuY29tLnNlYXRnZWVrLlNwcmVlZGx5QXBwbGVQYXlUZXN0MRMwEQYDVQQL
DAo5QjNRWTlXQlo1MRcwFQYDVQQKDA5TZWF0R2VlaywgSW5jLjELMAkGA1UEBhMC
VVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQhoBD6FaOXUJq3e4EoI7rWemTz
hLaPlAdF87WzmbhWKVNJ9LAEhrBjAtj6is765Ow2dnYta0QPF9EJoubwKOjKo4IC
VTCCAlEwRwYIKwYBBQUHAQEEOzA5MDcGCCsGAQUFBzABhitodHRwOi8vb2NzcC5h
cHBsZS5jb20vb2NzcDA0LWFwcGxld3dkcmNhMjAxMB0GA1UdDgQWBBQMV4lSAdev
m6sv1MVm5yR0gWij+jAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFIS2hMw6hmJy
FlmU6BqjvUjfOt8LMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4w
gcMGCCsGAQUFBwICMIG2DIGzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBi
eSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHRhbmNlIG9mIHRoZSB0aGVuIGFwcGxp
Y2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMgb2YgdXNlLCBjZXJ0
aWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3RhdGVt
ZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmlj
YXRlYXV0aG9yaXR5LzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmFwcGxl
LmNvbS9hcHBsZXd3ZHJjYTIuY3JsMA4GA1UdDwEB/wQEAwIDKDBPBgkqhkiG92Nk
BiAEQgxAODlDQjI1MDkxOTI0RDY3RjlFMEM2QUVDMzA0MENBMkFGNzA4MEYzRTBG
Q0NFMTZBOTY5RDkyMUE0QkM5RTA1RjAKBggqhkjOPQQDAgNJADBGAiEAvKYdzDtD
Q87guVNkybbcEY1Y/nXO9Ry+4fVDwXYMET0CIQDEiK1+xSSziPZ/PPQHF8MCWsD0
LDW0aLigLHbDgQcrXA==
-----END CERTIFICATE-----
]]>
</pem>
</certificate>
HTTPS/1.1 200 OK
{
"certificate": {
"token": "BHD5mnpizTjP9NhlQqUuIMs8qFF",
"algorithm": "ec-prime256v1",
"cn": "MyApp ApplePay Production Certificate",
"o": null,
"ou": null,
"c": null,
"st": null,
"l": null,
"email_address": "security@yourorg.com",
"public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIaAQ+hWjl1Cat3uBKCO61npk84S2\nj5QHRfO1s5m4VilTSfSwBIawYwLY+orO+uTsNnZ2LWtEDxfRCaLm8Cjoyg==\n-----END PUBLIC KEY-----\n",
"public_key_hash": "/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI=",
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBSTCB7wIBADCBjDEuMCwGA1UEAwwlTXlBcHAgQXBwbGVQYXkgUHJvZHVjdGlv\nbiBDZXJ0aWZpY2F0ZTEJMAcGA1UECgwAMQkwBwYDVQQLDAAxCTAHBgNVBAYTADEJ\nMAcGA1UECAwAMQkwBwYDVQQHDAAxIzAhBgkqhkiG9w0BCQEWFHNlY3VyaXR5QHlv\ndXJvcmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0fpMDOVsNWh56lzY\nLLT8AUv77xfxIDEH0EvVcoDIGjO1wHwrUhp/p8kSVXYEt5i+jzE7UHEUNwrD5YtC\n7i64hKAAMAoGCCqGSM49BAMCA0kAMEYCIQD0qoJM4EKR9DT6AIHNMm7I0Hwzu3rp\nu7CIFgdchCsNeQIhANCstbvSt7ZwQY4abRS9GiTlFn3vGGjwGdeeXb0RmxGg\n-----END CERTIFICATE REQUEST-----\n",
"pem": "-----BEGIN CERTIFICATE-----\nMIIEiTCCBC6gAwIBAgIIFRZ9ouKAzqwwCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMM\nK0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAk\nBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApB\ncHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNTAyMTkyMDMzMzBaFw0xNzAzMjAy\nMDMzMzBaMIG5MTowOAYKCZImiZPyLGQBAQwqbWVyY2hhbnQuY29tLnNlYXRnZWVr\nLlNwcmVlZGx5QXBwbGVQYXlUZXN0MUAwPgYDVQQDDDdNZXJjaGFudCBJRDogbWVy\nY2hhbnQuY29tLnNlYXRnZWVrLlNwcmVlZGx5QXBwbGVQYXlUZXN0MRMwEQYDVQQL\nDAo5QjNRWTlXQlo1MRcwFQYDVQQKDA5TZWF0R2VlaywgSW5jLjELMAkGA1UEBhMC\nVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQhoBD6FaOXUJq3e4EoI7rWemTz\nhLaPlAdF87WzmbhWKVNJ9LAEhrBjAtj6is765Ow2dnYta0QPF9EJoubwKOjKo4IC\nVTCCAlEwRwYIKwYBBQUHAQEEOzA5MDcGCCsGAQUFBzABhitodHRwOi8vb2NzcC5h\ncHBsZS5jb20vb2NzcDA0LWFwcGxld3dkcmNhMjAxMB0GA1UdDgQWBBQMV4lSAdev\nm6sv1MVm5yR0gWij+jAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFIS2hMw6hmJy\nFlmU6BqjvUjfOt8LMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4w\ngcMGCCsGAQUFBwICMIG2DIGzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBi\neSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHRhbmNlIG9mIHRoZSB0aGVuIGFwcGxp\nY2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMgb2YgdXNlLCBjZXJ0\naWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3RhdGVt\nZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmlj\nYXRlYXV0aG9yaXR5LzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmFwcGxl\nLmNvbS9hcHBsZXd3ZHJjYTIuY3JsMA4GA1UdDwEB/wQEAwIDKDBPBgkqhkiG92Nk\nBiAEQgxAODlDQjI1MDkxOTI0RDY3RjlFMEM2QUVDMzA0MENBMkFGNzA4MEYzRTBG\nQ0NFMTZBOTY5RDkyMUE0QkM5RTA1RjAKBggqhkjOPQQDAgNJADBGAiEAvKYdzDtD\nQ87guVNkybbcEY1Y/nXO9Ry+4fVDwXYMET0CIQDEiK1+xSSziPZ/PPQHF8MCWsD0\nLDW0aLigLHbDgQcrXA==\n-----END CERTIFICATE-----\n",
"created_at": "2017-06-27T18:16:35Z",
"updated_at": "2017-07-27T17:54:23Z"
}
}
<certificate>
<token>BHD5mnpizTjP9NhlQqUuIMs8qFF</token>
<algorithm>ec-prime256v1</algorithm>
<cn>MyApp ApplePay Production Certificate</cn>
<o nil="true"></o>
<ou nil="true"></ou>
<c nil="true"></c>
<st nil="true"></st>
<l nil="true"></l>
<email_address>security@yourorg.com</email_address>
<public_key>-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIaAQ+hWjl1Cat3uBKCO61npk84S2
j5QHRfO1s5m4VilTSfSwBIawYwLY+orO+uTsNnZ2LWtEDxfRCaLm8Cjoyg==
-----END PUBLIC KEY-----
</public_key>
<public_key_hash>/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI=</public_key_hash>
<csr>-----BEGIN CERTIFICATE REQUEST-----
MIIBSTCB7wIBADCBjDEuMCwGA1UEAwwlTXlBcHAgQXBwbGVQYXkgUHJvZHVjdGlv
biBDZXJ0aWZpY2F0ZTEJMAcGA1UECgwAMQkwBwYDVQQLDAAxCTAHBgNVBAYTADEJ
MAcGA1UECAwAMQkwBwYDVQQHDAAxIzAhBgkqhkiG9w0BCQEWFHNlY3VyaXR5QHlv
dXJvcmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0fpMDOVsNWh56lzY
LLT8AUv77xfxIDEH0EvVcoDIGjO1wHwrUhp/p8kSVXYEt5i+jzE7UHEUNwrD5YtC
7i64hKAAMAoGCCqGSM49BAMCA0kAMEYCIQD0qoJM4EKR9DT6AIHNMm7I0Hwzu3rp
u7CIFgdchCsNeQIhANCstbvSt7ZwQY4abRS9GiTlFn3vGGjwGdeeXb0RmxGg
-----END CERTIFICATE REQUEST-----
</csr>
<pem>-----BEGIN CERTIFICATE-----
MIIEiTCCBC6gAwIBAgIIFRZ9ouKAzqwwCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMM
K0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAk
BgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApB
cHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNTAyMTkyMDMzMzBaFw0xNzAzMjAy
MDMzMzBaMIG5MTowOAYKCZImiZPyLGQBAQwqbWVyY2hhbnQuY29tLnNlYXRnZWVr
LlNwcmVlZGx5QXBwbGVQYXlUZXN0MUAwPgYDVQQDDDdNZXJjaGFudCBJRDogbWVy
Y2hhbnQuY29tLnNlYXRnZWVrLlNwcmVlZGx5QXBwbGVQYXlUZXN0MRMwEQYDVQQL
DAo5QjNRWTlXQlo1MRcwFQYDVQQKDA5TZWF0R2VlaywgSW5jLjELMAkGA1UEBhMC
VVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQhoBD6FaOXUJq3e4EoI7rWemTz
hLaPlAdF87WzmbhWKVNJ9LAEhrBjAtj6is765Ow2dnYta0QPF9EJoubwKOjKo4IC
VTCCAlEwRwYIKwYBBQUHAQEEOzA5MDcGCCsGAQUFBzABhitodHRwOi8vb2NzcC5h
cHBsZS5jb20vb2NzcDA0LWFwcGxld3dkcmNhMjAxMB0GA1UdDgQWBBQMV4lSAdev
m6sv1MVm5yR0gWij+jAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFIS2hMw6hmJy
FlmU6BqjvUjfOt8LMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4w
gcMGCCsGAQUFBwICMIG2DIGzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBi
eSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHRhbmNlIG9mIHRoZSB0aGVuIGFwcGxp
Y2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMgb2YgdXNlLCBjZXJ0
aWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3RhdGVt
ZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmlj
YXRlYXV0aG9yaXR5LzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmFwcGxl
LmNvbS9hcHBsZXd3ZHJjYTIuY3JsMA4GA1UdDwEB/wQEAwIDKDBPBgkqhkiG92Nk
BiAEQgxAODlDQjI1MDkxOTI0RDY3RjlFMEM2QUVDMzA0MENBMkFGNzA4MEYzRTBG
Q0NFMTZBOTY5RDkyMUE0QkM5RTA1RjAKBggqhkjOPQQDAgNJADBGAiEAvKYdzDtD
Q87guVNkybbcEY1Y/nXO9Ry+4fVDwXYMET0CIQDEiK1+xSSziPZ/PPQHF8MCWsD0
LDW0aLigLHbDgQcrXA==
-----END CERTIFICATE-----
</pem>
<created_at type="dateTime">2017-06-27T18:16:35Z</created_at>
<updated_at type="dateTime">2017-07-27T17:54:24Z</updated_at>
</certificate>
Update an existing SSL certificate record with the signed certificate value (in PEM format).
URL Parameters
| Parameter | Description |
|---|---|
| certificate_token required |
A unique string generated by Spreedly to identify a certificate. |
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| certificate | Root element |
| ❯ pem required |
The signed certificate in PEM format. Spreedly is not a certificate authority and, thusly, will not sign the certificate for you. It is your responsibility to take the CSR to your certificate authority, and then update the certificate record with the signed cert in PEM format. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| certificate | Root element |
| ❯ algorithm | The encryption algorithm used to create the key pair |
| ❯ cn | The certificate common name |
| ❯ o | The organization |
| ❯ ou | The organization unit |
| ❯ c | The country |
| ❯ st | The state |
| ❯ l | The locality or city |
| ❯ email_address | The email address |
| ❯ public-key | PEM-formatted public key value |
| ❯ csr | PEM formatted certificate signing request |
| ❯ pem | The signed certificate in PEM format. Spreedly is not a certificate authority and, thusly, will not sign the certificate for you. It is your responsibility to take the CSR to your certificate authority (or self-sign the cert), and then update the certificate record with the signed cert in PEM format. |
Transactions
Every action performed against the Spreedly API is captured as a transaction. Transactions can represent local actions, such as storing a payment method, or an external action, such as performing a purchase against a gateway. 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 Transaction.
Confirm (Offsite transactions)
Attempts to confirm a pending offsite purchase, offsite synchronous purchase or offsite synchronous authorization.
Braintree
- A
processingtransaction with apayment_method_typeof ‘paypal’ or 'venmo’ is needed to confirm this transaction. - A object returned in iFrame. This could contain the following parameters;
state,nonce,payment_method,device_date,username
Please see our Braintree APM section 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_methodof type 'stripe_apm’ is needed to confirm this transaction. - A
payment_method_tokenor credit card details in apayment_methodobject must be passed.
Please see our Stripe APM guide for more information and reference implementations.
POST /v1/transactions/D4EkbtWlUtWmfK5QvhttGsBktRj/confirm.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6"
}
}
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:01:45Z",
"updated_at": "2018-11-07T15:01:45Z",
"succeeded": true,
"state": "succeeded",
"token": "a8CseM5RdIhHQwsgCKTZLi9UhSo",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "49",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:01:45Z",
"updated_at": "2018-11-07T15:01:45Z"
},
"shipping_address": {
"name": "Joe Smith",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "ZjcXez8r5tOkQ4wjXDCv5lZ6pKg",
"created_at": "2018-11-07T15:01:45Z",
"updated_at": "2018-11-07T15:01:45Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Smith",
"month": 12,
"year": 2018,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Joe Smith",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:01:44Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:44Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>HlOybss40Zr3hwCqqwRKBlYmXsi</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<sub_merchant_key nil="true"></sub_merchant_key>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>47</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Joey Jones</name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2018-11-07T15:01:44Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:44Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>TtdNEGumPZzS7RWBiwj4ejLpHbd</token>
<created_at type="dateTime">2018-11-07T15:01:44Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:44Z</updated_at>
<email nil="true"></email>
<data nil="true"></data>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"></metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<month type="integer">3</month>
<year type="integer">2020</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Joey Jones</full_name>
<eligible_for_card_updater nil="true"></eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Complete (3DS 2)
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_actionofdevice_fingerprintwill fire atrigger-completionevent 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 callcompleteso that the latest transaction state can be retrieved in case of a timeout. - A pending transaction with a
required_actionofchallengewill fire afinalization-timeoutwhen ourSpreedly.ThreeDS.Lifecyclestops polling for updates after 10-15 minutes of not receiving a new status. When this event is received, it is recommended that merchants callcompleteso that the transaction state can be updated due to cardholder abandonment or missed callbacks.
Please see our 3DS 2 guides for more information and reference implementations.
POST /v1/transactions/D4EkbtWlUtWmfK5QvhttGsBktRj/complete.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2021-06-01T16:14:14Z",
"updated_at": "2021-06-01T16:14:14Z",
"succeeded": true,
"state": "succeeded",
"token": "WYWKUodgezds18eT6xdWde6TIQ6",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "55",
"gateway_latency_ms": 0,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"warning": null,
"application_id": null,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful authorize",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2021-06-01T16:14:14Z",
"updated_at": "2021-06-01T16:14:14Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2021-06-01T16:14:14Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2021-06-01T16:14:13Z</created_at>
<updated_at type="dateTime">2021-06-01T16:14:13Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>KMRQGOgdSGyyCOimswKxSpXFG6O</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<merchant_profile_key nil="true"></merchant_profile_key>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>50</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<stored_credential_initiator nil="true"></stored_credential_initiator>
<stored_credential_reason_type nil="true"></stored_credential_reason_type>
<warning nil="true"></warning>
<application_id nil="true"></application_id>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2021-06-01T16:14:13Z</created_at>
<updated_at type="dateTime">2021-06-01T16:14:13Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at>2017-06-26T17:04:38Z</created_at>
<updated_at>2021-06-01T16:14:13Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying the transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ transaction_type | The type of transaction, e.g., Authorization, Capture, Credit |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ required_action | The required action in the 3DS 2 flow, e.g., none, device_fingerprint, challenge, etc |
List
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"transactions": [
{
"token": "XWV55noINCMAAjXhr1ppj0kjvCd",
"created_at": "2017-06-22T13:19:11Z",
"updated_at": "2017-06-22T13:19:11Z",
"succeeded": true,
"transaction_type": "AddGateway",
"state": "succeeded",
"gateway": {
"token": "CtehwikoMnllHsr3XFfAY1EzPkN",
"gateway_type": "test",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"google_pay"
],
"state": "retained",
"created_at": "2017-06-22T13:19:11Z",
"updated_at": "2017-11-27T21:08:11Z",
"name": "Spreedly Test",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"offsite_synchronous_purchase",
"offsite_synchronous_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials"
],
"credentials": [
],
"gateway_settings": {
},
"gateway_specific_fields": [
"simulate_error",
"simulate_decline",
"idempotency_key",
"mit_override_demo"
],
"redacted": false,
"sandbox": false,
"mode": "default"
},
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!"
},
{
"token": "Xqdiohe6ue8Zgb7I52j6BA843Y1",
"created_at": "2017-06-22T14:16:23Z",
"updated_at": "2017-06-22T14:16:23Z",
"succeeded": true,
"transaction_type": "AddGateway",
"state": "succeeded",
"gateway": {
"token": "7NTzuQfnaNU2Jr4cVgOt7jfTVGq",
"gateway_type": "test",
"description": null,
"merchant_profile_key": null,
"sub_merchant_key": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"google_pay"
],
"state": "retained",
"created_at": "2017-06-22T14:16:23Z",
"updated_at": "2017-11-27T21:44:49Z",
"name": "Spreedly Test",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"offsite_synchronous_purchase",
"offsite_synchronous_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"3dsecure_2_mpi_purchase",
"3dsecure_2_mpi_authorize",
"store",
"remove",
"network_tokenization",
"populate_mit_fields",
"transaction_retry",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize",
"stored_credentials"
],
"credentials": [
],
"gateway_settings": {
},
"gateway_specific_fields": [
"simulate_error",
"simulate_decline",
"idempotency_key",
"mit_override_demo"
],
"redacted": false,
"sandbox": false,
"mode": "default"
},
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!"
}
]
}
<transactions>
<transaction>
<token>XWV55noINCMAAjXhr1ppj0kjvCd</token>
<created_at type="dateTime">2017-06-22T13:19:11Z</created_at>
<updated_at type="dateTime">2017-06-22T13:19:11Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddGateway</transaction_type>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway>
<token>CtehwikoMnllHsr3XFfAY1EzPkN</token>
<gateway_type>test</gateway_type>
<name>Spreedly Test</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_reference_authorization type="boolean">true</supports_reference_authorization>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>simulate_error</gateway_specific_field>
<gateway_specific_field>simulate_decline</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>mit_override_demo</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>sprel</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2017-06-22T13:19:11Z</created_at>
<updated_at type="dateTime">2017-11-27T21:08:11Z</updated_at>
</gateway>
</transaction>
<transaction>
<token>Xqdiohe6ue8Zgb7I52j6BA843Y1</token>
<created_at type="dateTime">2017-06-22T14:16:23Z</created_at>
<updated_at type="dateTime">2017-06-22T14:16:23Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddGateway</transaction_type>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway>
<token>7NTzuQfnaNU2Jr4cVgOt7jfTVGq</token>
<gateway_type>test</gateway_type>
<name>Spreedly Test</name>
<description nil="true"></description>
<merchant_profile_key nil="true"></merchant_profile_key>
<sub_merchant_key nil="true"></sub_merchant_key>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">true</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">true</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
<supports_reference_authorization type="boolean">true</supports_reference_authorization>
<supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
<supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>simulate_error</gateway_specific_field>
<gateway_specific_field>simulate_decline</gateway_specific_field>
<gateway_specific_field>idempotency_key</gateway_specific_field>
<gateway_specific_field>mit_override_demo</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>sprel</payment_method>
<payment_method>third_party_token</payment_method>
<payment_method>bank_account</payment_method>
<payment_method>apple_pay</payment_method>
<payment_method>google_pay</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2017-06-22T14:16:23Z</created_at>
<updated_at type="dateTime">2017-11-27T21:44:49Z</updated_at>
</gateway>
</transaction>
</transactions>
Retrieve an ordered and paginated list of all transactions in the authenticated environment.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
| state | The transaction state on which to filter the returned list. Can be one of succeeded, failed, gateway_processing_failed, gateway_processing_result_unknown. |
| count | The number of transactions to return. By default returns 20, maximum allowed is 100. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transactions | Root element |
| ❯ token | The token uniquely identifying the transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ transaction_type | The type of transaction, e.g., Authorization, Capture, Credit |
Show
GET /v1/transactions/D4EkbtWlUtWmfK5QvhttGsBktRj.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2021-06-01T16:14:14Z",
"updated_at": "2021-06-01T16:14:14Z",
"succeeded": true,
"state": "succeeded",
"token": "WYWKUodgezds18eT6xdWde6TIQ6",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "55",
"gateway_latency_ms": 0,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"warning": null,
"application_id": null,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful authorize",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2021-06-01T16:14:14Z",
"updated_at": "2021-06-01T16:14:14Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2021-06-01T16:14:14Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2021-06-01T16:14:13Z</created_at>
<updated_at type="dateTime">2021-06-01T16:14:13Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>KMRQGOgdSGyyCOimswKxSpXFG6O</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<merchant_profile_key nil="true"></merchant_profile_key>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>50</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<stored_credential_initiator nil="true"></stored_credential_initiator>
<stored_credential_reason_type nil="true"></stored_credential_reason_type>
<warning nil="true"></warning>
<application_id nil="true"></application_id>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2021-06-01T16:14:13Z</created_at>
<updated_at type="dateTime">2021-06-01T16:14:13Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at>2017-06-26T17:04:38Z</created_at>
<updated_at>2021-06-01T16:14:13Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
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 dashboard.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying this transaction at Spreedly |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying the transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ transaction_type | The type of transaction. |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
Update
PATCH /v1/transactions/Rs0JRsByYUEPqh3wL0hPzG6oBcW.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": false,
"created_at": "2022-11-04T17:15:05Z",
"updated_at": "2022-11-04T17:15:05Z",
"succeeded": true,
"state": "succeeded",
"token": "2AhGXGZpm5IqetB3PHHId7hH12s",
"transaction_type": "UpdateTransaction",
"original_transaction_updated": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "example_gateway_brand",
"original_transaction": {
"on_test_gateway": false,
"created_at": "2022-10-27T14:55:46Z",
"updated_at": "2022-10-27T14:55:50Z",
"succeeded": true,
"state": "succeeded",
"token": "Rs0JRsByYUEPqh3wL0hPzG6oBcW",
"transaction_type": "Purchase",
"order_id": "44837",
"gateway_transaction_id": "1309352841",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "example_gateway_brand",
"response": {
"success": true,
"message": "purchase complete",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2022-10-27T14:55:47Z",
"updated_at": "2022-10-27T14:55:50Z"
}
}
}
}
<transaction>
<on_test_gateway type="boolean">false</on_test_gateway>
<created_at type="dateTime">2022-11-04T17:15:05Z</created_at>
<updated_at type="dateTime">2022-11-04T17:15:05Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>2AhGXGZpm5IqetB3PHHId7hH12s</token>
<transaction_type>UpdateTransaction</transaction_type>
<original_transaction_updated type="boolean">true</original_transaction_updated>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>example_gateway_brand</gateway_type>
<original_transaction>
<on_test_gateway type="boolean">false</on_test_gateway>
<created_at type="dateTime">2022-10-27T14:55:46Z</created_at>
<updated_at type="dateTime">2022-10-27T14:55:50Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>Rs0JRsByYUEPqh3wL0hPzG6oBcW</token>
<transaction_type>Purchase</transaction_type>
<order_id>44837</order_id>
<gateway_transaction_id>1309352841</gateway_transaction_id>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>example_gateway_brand</gateway_type>
<response>
<success type="boolean">true</success>
<message>purchase complete</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2022-10-27T14:55:47Z</created_at>
<updated_at type="dateTime">2022-10-27T14:55:50Z</updated_at>
</response>
</original_transaction>
</transaction>
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 documentation for more information.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying this transaction at Spreedly |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ state | The state of the transaction, valid states depend on the type of transaction |
| ❯ token | The token uniquely identifying the transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ transaction_type | The type of transaction, e.g., Authorization, Capture, Credit |
| ❯ original_transaction_updated | true if the original transaction record was ever successfully updated, false otherwise |
| ❯ gateway_token | The token uniquely identifying the gateway at Spreedly |
| ❯ gateway_type | The human-readable identifier of the brand of the gateway |
| ❯ original_transaction | Notable fields of the original transaction. The original transaction’s state may or may not have been updated. See our documentation for more information on why a transaction may or may not be updated. |
Transcript
GET /v1/transactions/<transaction_token>/transcript HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
[*>] POST to https://spreedly-echo.herokuapp.com
Content-Type: application/json
X-App-Id: 1234
X-App-Secret: [FILTERED]
{
"product_id":"916593",
"card_number":"[FILTERED]",
"card_cvv":"[FILTERED]",
"first_name":"Newfirst",
"last_name":"Newlast",
"year":"2032",
"month":"3"
}
[<*] Response 200 received in 0s
Date: Thu, 27 Jul 2017 17:55:48 GMT
Connection: close
Host: spreedly-echo.herokuapp.com
Accept: */*
User_agent: spreedly-agent/Typhoeus 0.6.9
X_request_id: e7473785-4070-4780-9e3a-66a84bbd2ca6
X_forwarded_for: 167.88.149.182
X_forwarded_proto: https
X_forwarded_port: 443
Via: 1.1 vegur, 1.1 vegur
Connect_time: 2
X_request_start: 1501178148676
Total_route_time: 0
X-Runtime: 0.000143
Server: thin 1.6.2 codename Doc Brown
HOST: spreedly-echo.herokuapp.com
CONNECTION: close
ACCEPT: */*
USER_AGENT: spreedly-agent/Typhoeus 0.6.9
X_REQUEST_ID: e7473785-4070-4780-9e3a-66a84bbd2ca6
X_FORWARDED_FOR: 167.88.149.182
X_FORWARDED_PROTO: https
X_FORWARDED_PORT: 443
VIA: 1.1 vegur
CONNECT_TIME: 2
X_REQUEST_START: 1501178148676
TOTAL_ROUTE_TIME: 0
{
"product_id":"916593",
"card_number":"[FILTERED]",
"card_cvv":"",
"first_name":"Newfirst",
"last_name":"Newlast",
"year":"2032",
"month":"3"
}
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.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying the transaction whose transcript is being requested |
Response Body
Text formatted representation of the communication between Spreedly and the external service.
Composer
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-in credit card Verify
POST /v1/transactions/verify.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"credit_card": {
"first_name": "Joe",
"last_name": "Smith",
"number": "4111111111111111",
"verification_value": "123",
"month": "12",
"year": "2029"
},
"retain_on_success": true,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q"
}
}
<transaction>
<credit_card>
<first_name>Joe</first_name>
<last_name>Smith</last_name>
<number>4111111111111111</number>
<verification_value>123</verification_value>
<month>12</month>
<year>2029</year>
</credit_card>
<retain_on_success>true</retain_on_success>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-07-02T19:07:48Z",
"updated_at": "2024-07-02T19:07:49Z",
"succeeded": true,
"state": "succeeded",
"token": "3P8y4b8oPVhhYvwuxNHLqIuObd0",
"transaction_type": "Verification",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_transaction_id": "qh7vrqjt",
"sub_merchant_key": null,
"gateway_latency_ms": 1052,
"warning": null,
"application_id": "Spreedly_BT",
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"gateway_response": {
"card_metadata": {
"issuer_country": "Unknown",
"card_type": "Unknown"
},
"merchant_data": {
"fraud_result": "Approve"
},
"raw_payment_outcome_data": {
"authorization_code": "643SBL",
"network_transaction_id": "020240702190749"
}
},
"retain_on_success": false,
"payment_method_added": true,
"smart_routed": false,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"populate_mit_fields": false,
"transaction_metadata": {
"risk": "low",
"type": "standard"
},
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "21SZ6WB2MN8E7TSQJHMB8G8RCB",
"gateway_type": "braintree",
"response": {
"success": true,
"message": "1000 Approved",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "M",
"cvv_message": "",
"pending": false,
"result_unknown": false,
"error_code": "1000",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-07-02T19:07:49Z",
"updated_at": "2024-07-02T19:07:49Z",
"network_transaction_id": "020240702190749"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1F3Z9AWA6Z9H5SHE196SZRQJYH",
"created_at": "2024-07-02T19:07:48.227Z",
"updated_at": "2024-07-02T19:07:48.227Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Smith",
"month": 12,
"year": 2029,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Joe Smith",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"bin_metadata": {
"card_brand": "VISA",
"issuing_bank": "CONOTOXIA SP. Z O.O",
"card_type": "DEBIT",
"card_category": "CLASSIC",
"issuing_country_iso_number": "616",
"issuing_bank_website": null,
"issuing_bank_phone_number": null,
"max_pan_length": 16,
"bin_type": "PERSONAL",
"regulated": "N"
},
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "56168f5bde6c0454f65eb6ccfc4ff4c3b80e",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2024-07-02T19:07:46Z</created_at>
<updated_at type="dateTime">2024-07-02T19:07:47Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>13rQv0AkmWwi98NHkRsiFBATT2</token>
<transaction_type>Verification</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<merchant_profile_key nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_transaction_id>5xh650sg</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">809</gateway_latency_ms>
<warning nil="true"/>
<application_id>Spreedly_BT</application_id>
<risk_data nil="true"/>
<merchant_metadata nil="true"/>
<customer_data nil="true"/>
<order_data nil="true"/>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<gateway_response>
<card_metadata>
<issuer_country>Unknown</issuer_country>
<card_type>Unknown</card_type>
</card_metadata>
<merchant_data>
<fraud_result>Approve</fraud_result>
</merchant_data>
<raw_payment_outcome_data>
<authorization_code>4CF8HZ</authorization_code>
<network_transaction_id>020240702190747</network_transaction_id>
</raw_payment_outcome_data>
</gateway_response>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<populate_mit_fields type="boolean">false</populate_mit_fields>
<transaction_metadata>
<risk>low</risk>
<type>standard</type>
</transaction_metadata>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>21SZ6WB2MN8E7TSQJHMB8G8RCB</gateway_token>
<gateway_type>braintree</gateway_type>
<shipping_address>
<name nil="true"/>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>1000 Approved</message>
<avs_code>I</avs_code>
<avs_message>Address not verified.</avs_message>
<cvv_code>M</cvv_code>
<cvv_message></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code>1000</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2024-07-02T19:07:47Z</created_at>
<updated_at type="dateTime">2024-07-02T19:07:47Z</updated_at>
<network_transaction_id>020240702190747</network_transaction_id>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1X9PDEM9539FFRWHPJ7T1ZDZ1H</token>
<created_at>2024-07-02T19:07:46.722Z</created_at>
<updated_at>2024-07-02T19:07:46.722Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joe</first_name>
<last_name>Smith</last_name>
<month type="integer">12</month>
<year type="integer">2029</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Joe Smith</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<bin_metadata>
<card_brand>VISA</card_brand>
<issuing_bank>CONOTOXIA SP. Z O.O</issuing_bank>
<card_type>DEBIT</card_type>
<card_category>CLASSIC</card_category>
<issuing_country_iso_number>616</issuing_country_iso_number>
<issuing_bank_website nil="true"/>
<issuing_bank_phone_number nil="true"/>
<max_pan_length type="integer">16</max_pan_length>
<bin_type>PERSONAL</bin_type>
<regulated>N</regulated>
</bin_metadata>
<fingerprint>56168f5bde6c0454f65eb6ccfc4ff4c3b80e</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ credit_card | Credit card element |
| ❯❯ first_name required |
The first name of the cardholder |
| ❯❯ last_name required |
The last name of the cardholder |
| ❯❯ number required |
The full card number |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
| ❯❯ month required |
The expiration month of the card |
| ❯❯ year required |
The expiration year of the card |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the cardholder. If provided, will be parsed to determine first_name and last_name. |
| ❯ workflow_key optional |
The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment’s default workflow_key if no value is provided |
| ❯ risk_data optional |
Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ merchant_metadata optional |
Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ customer_data optional |
Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_data optional |
Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_id optional |
The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description optional |
A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ ip optional |
The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| ❯ email optional |
Override the customer email address associated with the payment method for this transaction |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address optional |
Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name optional |
Customer’s name in the shipping address |
| ❯❯ address1 optional |
Customer’s shipping address, line 1 |
| ❯❯ address2 optional |
Customer’s shipping address, line 2 |
| ❯❯ city optional |
Customer’s shipping city |
| ❯❯ state optional |
Customer’s shipping state/province |
| ❯❯ zip optional |
Customer’s shipping zip |
| ❯❯ country optional |
Customer’s shipping country |
| ❯❯ phone_number optional |
Customer’s shipping phone |
| ❯ billing_address optional |
Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name optional |
Customer’s name in the billing address |
| ❯❯ address1 optional |
Customer’s billing address, line 1 |
| ❯❯ address2 optional |
Customer’s billing address, line 2 |
| ❯❯ city optional |
Customer’s billing city |
| ❯❯ state optional |
Customer’s billing state/province |
| ❯❯ zip optional |
Customer’s billing zip |
| ❯❯ country optional |
Customer’s billing country |
| ❯❯ phone_number optional |
Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ allow_blank_name optional |
true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date optional |
true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date optional |
true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_response | A hash containing normalized fields from various gateways. Please see our normalized response field documentation for more info |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ gateway_type | The gateway used for this transaction. |
| ❯ gateway_token | The key of the gateway used for this transaction. |
| ❯ workflow_key | The key of the workflow used for this transaction. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Payment Method Token Verify
POST /v1/transactions/verify.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"retain_on_success": true,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<retain_on_success>true</retain_on_success>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-07-02T19:13:39Z",
"updated_at": "2024-07-02T19:13:40Z",
"succeeded": true,
"state": "succeeded",
"token": "3t2AjIFBeLvGSqPjZapES3L3R29",
"transaction_type": "Verification",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_transaction_id": "9pxg3xqt",
"sub_merchant_key": null,
"gateway_latency_ms": 689,
"warning": null,
"application_id": "Spreedly_BT",
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"gateway_response": {
"card_metadata": {
"issuer_country": "Unknown",
"card_type": "Unknown"
},
"merchant_data": {
"fraud_result": "Approve"
},
"raw_payment_outcome_data": {
"authorization_code": "5TYVK6",
"network_transaction_id": "020240702191340"
}
},
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"populate_mit_fields": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "21SZ6WB2MN8E7TSQJHMB8G8RCB",
"gateway_type": "braintree",
"response": {
"success": true,
"message": "1000 Approved",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "I",
"cvv_message": "",
"pending": false,
"result_unknown": false,
"error_code": "1000",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-07-02T19:13:40Z",
"updated_at": "2024-07-02T19:13:40Z",
"network_transaction_id": "020240702191340"
},
"shipping_address": {
"name": "Joe Jones",
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313"
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "56G9BCQSC78W5V70JSNFNCFZR0",
"created_at": "2024-07-02T19:12:59.024Z",
"updated_at": "2024-07-02T19:13:39.529Z",
"email": "joey@example.com",
"data": null,
"storage_state": "retained",
"test": true,
"metadata": {
"another_key": 123,
"final_key": true,
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Jones",
"month": 1,
"year": 2029,
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313",
"company": "Acme Inc.",
"full_name": "Joe Jones",
"eligible_for_card_updater": true,
"shipping_address1": "33 Lane Road",
"shipping_address2": "Apartment 4",
"shipping_city": "Wanaque",
"shipping_state": "NJ",
"shipping_zip": "31331",
"shipping_country": "US",
"shipping_phone_number": "919.331.3313",
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"bin_metadata": {
"card_brand": "VISA",
"issuing_bank": "CONOTOXIA SP. Z O.O",
"card_type": "DEBIT",
"card_category": "CLASSIC",
"issuing_country_iso_number": "616",
"issuing_bank_website": null,
"issuing_bank_phone_number": null,
"max_pan_length": 16,
"bin_type": "PERSONAL",
"regulated": "N"
},
"payment_method_type": "credit_card",
"stored_credential_usage": {
"braintree": {
"original_network_transaction_id": "020240702191336",
"network_transaction_id": "020240702191340"
},
"scheme_issued": {
"original_network_transaction_id": "020240702191336",
"network_transaction_id": "020240702191340"
}
},
"errors": [
],
"fingerprint": "56168f5bde6c0454f65eb6ccfc4ff4c3b80e",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2024-07-02T19:13:38Z</created_at>
<updated_at type="dateTime">2024-07-02T19:13:39Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>TU2aFmPhvE5tzqoBHD78vQhONhR</token>
<transaction_type>Verification</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<merchant_profile_key nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_transaction_id>fa92mc8k</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">850</gateway_latency_ms>
<warning nil="true"/>
<application_id>Spreedly_BT</application_id>
<risk_data nil="true"/>
<merchant_metadata nil="true"/>
<customer_data nil="true"/>
<order_data nil="true"/>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<gateway_response>
<card_metadata>
<issuer_country>Unknown</issuer_country>
<card_type>Unknown</card_type>
</card_metadata>
<merchant_data>
<fraud_result>Approve</fraud_result>
</merchant_data>
<raw_payment_outcome_data>
<authorization_code>53DL9Q</authorization_code>
<network_transaction_id>020240702191339</network_transaction_id>
</raw_payment_outcome_data>
</gateway_response>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<populate_mit_fields type="boolean">false</populate_mit_fields>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>21SZ6WB2MN8E7TSQJHMB8G8RCB</gateway_token>
<gateway_type>braintree</gateway_type>
<shipping_address>
<name>Joe Jones</name>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>1000 Approved</message>
<avs_code>I</avs_code>
<avs_message>Address not verified.</avs_message>
<cvv_code>I</cvv_code>
<cvv_message></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code>1000</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2024-07-02T19:13:39Z</created_at>
<updated_at type="dateTime">2024-07-02T19:13:39Z</updated_at>
<network_transaction_id>020240702191339</network_transaction_id>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>56G9BCQSC78W5V70JSNFNCFZR0</token>
<created_at>2024-07-02T19:12:59.024Z</created_at>
<updated_at>2024-07-02T19:13:38.218Z</updated_at>
<email>joey@example.com</email>
<data nil="true"/>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<another_key type="integer">123</another_key>
<final_key type="boolean">true</final_key>
<key>string value</key>
</metadata>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joe</first_name>
<last_name>Jones</last_name>
<month type="integer">1</month>
<year type="integer">2029</year>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
<company>Acme Inc.</company>
<full_name>Joe Jones</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1>33 Lane Road</shipping_address1>
<shipping_address2>Apartment 4</shipping_address2>
<shipping_city>Wanaque</shipping_city>
<shipping_state>NJ</shipping_state>
<shipping_zip>31331</shipping_zip>
<shipping_country>US</shipping_country>
<shipping_phone_number>919.331.3313</shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<stored_credential_usage>
<braintree>
<original_network_transaction_id>020240702191336</original_network_transaction_id>
<network_transaction_id>020240702191339</network_transaction_id>
</braintree>
<scheme_issued>
<original_network_transaction_id>020240702191336</original_network_transaction_id>
<network_transaction_id>020240702191339</network_transaction_id>
</scheme_issued>
</stored_credential_usage>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<bin_metadata>
<card_brand>VISA</card_brand>
<issuing_bank>CONOTOXIA SP. Z O.O</issuing_bank>
<card_type>DEBIT</card_type>
<card_category>CLASSIC</card_category>
<issuing_country_iso_number>616</issuing_country_iso_number>
<issuing_bank_website nil="true"/>
<issuing_bank_phone_number nil="true"/>
<max_pan_length type="integer">16</max_pan_length>
<bin_type>PERSONAL</bin_type>
<regulated>N</regulated>
</bin_metadata>
<fingerprint>56168f5bde6c0454f65eb6ccfc4ff4c3b80e</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ workflow_key optional |
The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment’s default workflow_key if no value is provided |
| ❯ risk_data optional |
Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ merchant_metadata optional |
Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ customer_data optional |
Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_data optional |
Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_id optional |
The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description optional |
A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ ip optional |
The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| ❯ email optional |
Override the customer email address associated with the payment method for this transaction |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address optional |
Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name optional |
Customer’s name in the shipping address |
| ❯❯ address1 optional |
Customer’s shipping address, line 1 |
| ❯❯ address2 optional |
Customer’s shipping address, line 2 |
| ❯❯ city optional |
Customer’s shipping city |
| ❯❯ state optional |
Customer’s shipping state/province |
| ❯❯ zip optional |
Customer’s shipping zip |
| ❯❯ country optional |
Customer’s shipping country |
| ❯❯ phone_number optional |
Customer’s shipping phone |
| ❯ billing_address optional |
Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name optional |
Customer’s name in the billing address |
| ❯❯ address1 optional |
Customer’s billing address, line 1 |
| ❯❯ address2 optional |
Customer’s billing address, line 2 |
| ❯❯ city optional |
Customer’s billing city |
| ❯❯ state optional |
Customer’s billing state/province |
| ❯❯ zip optional |
Customer’s billing zip |
| ❯❯ country optional |
Customer’s billing country |
| ❯❯ phone_number optional |
Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ allow_blank_name optional |
true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date optional |
true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date optional |
true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_response | A hash containing normalized fields from various gateways. Please see our normalized response field documentation for more info |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ gateway_type | The gateway used for this transaction. |
| ❯ gateway_token | The key of the gateway used for this transaction. |
| ❯ workflow_key | The key of the workflow used for this transaction. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in credit card Authorize
POST /v1/transactions/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"credit_card": {
"first_name": "Joe",
"last_name": "Smith",
"number": "4111111111111111",
"verification_value": "123",
"month": "12",
"year": "2029"
},
"amount": 100,
"currency_code": "USD",
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"transaction_metadata": {
"risk": "low",
"type": "standard"
}
}
}
<transaction>
<credit_card>
<first_name>Joe</first_name>
<last_name>Smith</last_name>
<number>4111111111111111</number>
<verification_value>123</verification_value>
<month>12</month>
<year>2029</year>
</credit_card>
<amount>100</amount>
<currency_code>USD</currency_code>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<transaction_metadata>
<risk>low</risk>
<type>standard</type>
</transaction_metadata>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-07-02T19:07:45Z",
"updated_at": "2024-07-02T19:07:46Z",
"succeeded": true,
"state": "succeeded",
"token": "HbvgGpAOziHerx1WcHLscQJMDep",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_transaction_id": "n4c1hnxx",
"sub_merchant_key": null,
"gateway_latency_ms": 500,
"warning": null,
"application_id": "Spreedly_BT",
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"gateway_response": {
"card_metadata": {
"issuer_country": "Unknown",
"card_type": "Unknown"
},
"merchant_data": {
"fraud_result": "Not Evaluated"
},
"raw_payment_outcome_data": {
"authorization_code": "DW8G9K",
"network_transaction_id": "020240702190745"
}
},
"amount": 100,
"local_amount": null,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"smart_routed": false,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"populate_mit_fields": false,
"transaction_metadata": {
"risk": "low",
"type": "standard"
},
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "21SZ6WB2MN8E7TSQJHMB8G8RCB",
"gateway_type": "braintree",
"response": {
"success": true,
"message": "1000 Approved",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "M",
"cvv_message": "",
"pending": false,
"result_unknown": false,
"error_code": "1000",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-07-02T19:07:45Z",
"updated_at": "2024-07-02T19:07:46Z",
"network_transaction_id": "020240702190745"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "4KM2ZTQV4D8P7THDF5KCXPQVR3",
"created_at": "2024-07-02T19:07:45.169Z",
"updated_at": "2024-07-02T19:07:45.169Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Smith",
"month": 12,
"year": 2029,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Joe Smith",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"bin_metadata": {
"card_brand": "VISA",
"issuing_bank": "CONOTOXIA SP. Z O.O",
"card_type": "DEBIT",
"card_category": "CLASSIC",
"issuing_country_iso_number": "616",
"issuing_bank_website": null,
"issuing_bank_phone_number": null,
"max_pan_length": 16,
"bin_type": "PERSONAL",
"regulated": "N"
},
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "56168f5bde6c0454f65eb6ccfc4ff4c3b80e",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2024-07-02T19:07:43Z</created_at>
<updated_at type="dateTime">2024-07-02T19:07:44Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>RffteQn6qXyVTfFmA9ylMgRpMkb</token>
<transaction_type>Authorization</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<merchant_profile_key nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_transaction_id>eqcgyw65</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">765</gateway_latency_ms>
<warning nil="true"/>
<application_id>Spreedly_BT</application_id>
<risk_data nil="true"/>
<merchant_metadata nil="true"/>
<customer_data nil="true"/>
<order_data nil="true"/>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<gateway_response>
<card_metadata>
<issuer_country>Unknown</issuer_country>
<card_type>Unknown</card_type>
</card_metadata>
<merchant_data>
<fraud_result>Approve</fraud_result>
</merchant_data>
<raw_payment_outcome_data>
<authorization_code>G2WFCQ</authorization_code>
<network_transaction_id>020240702190743</network_transaction_id>
</raw_payment_outcome_data>
</gateway_response>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<populate_mit_fields type="boolean">false</populate_mit_fields>
<transaction_metadata>
<risk>low</risk>
<type>standard</type>
</transaction_metadata>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>21SZ6WB2MN8E7TSQJHMB8G8RCB</gateway_token>
<gateway_type>braintree</gateway_type>
<shipping_address>
<name nil="true"/>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>1000 Approved</message>
<avs_code>I</avs_code>
<avs_message>Address not verified.</avs_message>
<cvv_code>M</cvv_code>
<cvv_message></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code>1000</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2024-07-02T19:07:44Z</created_at>
<updated_at type="dateTime">2024-07-02T19:07:44Z</updated_at>
<network_transaction_id>020240702190743</network_transaction_id>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>5P6HCD2NQW91WT865BQASCYV3G</token>
<created_at>2024-07-02T19:07:43.165Z</created_at>
<updated_at>2024-07-02T19:07:43.165Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joe</first_name>
<last_name>Smith</last_name>
<month type="integer">12</month>
<year type="integer">2029</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Joe Smith</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<bin_metadata>
<card_brand>VISA</card_brand>
<issuing_bank>CONOTOXIA SP. Z O.O</issuing_bank>
<card_type>DEBIT</card_type>
<card_category>CLASSIC</card_category>
<issuing_country_iso_number>616</issuing_country_iso_number>
<issuing_bank_website nil="true"/>
<issuing_bank_phone_number nil="true"/>
<max_pan_length type="integer">16</max_pan_length>
<bin_type>PERSONAL</bin_type>
<regulated>N</regulated>
</bin_metadata>
<fingerprint>56168f5bde6c0454f65eb6ccfc4ff4c3b80e</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ credit_card | Credit card element |
| ❯❯ first_name required |
The first name of the cardholder |
| ❯❯ last_name required |
The last name of the cardholder |
| ❯❯ number required |
The full card number |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
| ❯❯ month required |
The expiration month of the card |
| ❯❯ year required |
The expiration year of the card |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the cardholder. If provided, will be parsed to determine first_name and last_name. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ stored_credential_initiator optional |
Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type optional |
What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ stored_credential_alternate_gateway optional |
String containing a specific gateway type or “scheme_issued”. Indicates which NTID to use if first time transacting on a gateway type. |
| ❯ workflow_key optional |
The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment’s default workflow_key if no value is provided |
| ❯ risk_data optional |
Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ merchant_metadata optional |
Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ customer_data optional |
Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_data optional |
Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_id optional |
The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description optional |
A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ ip optional |
The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| ❯ email optional |
Override the customer email address associated with the payment method for this transaction |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address optional |
Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name optional |
Customer’s name in the shipping address |
| ❯❯ address1 optional |
Customer’s shipping address, line 1 |
| ❯❯ address2 optional |
Customer’s shipping address, line 2 |
| ❯❯ city optional |
Customer’s shipping city |
| ❯❯ state optional |
Customer’s shipping state/province |
| ❯❯ zip optional |
Customer’s shipping zip |
| ❯❯ country optional |
Customer’s shipping country |
| ❯❯ phone_number optional |
Customer’s shipping phone |
| ❯ billing_address optional |
Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name optional |
Customer’s name in the billing address |
| ❯❯ address1 optional |
Customer’s billing address, line 1 |
| ❯❯ address2 optional |
Customer’s billing address, line 2 |
| ❯❯ city optional |
Customer’s billing city |
| ❯❯ state optional |
Customer’s billing state/province |
| ❯❯ zip optional |
Customer’s billing zip |
| ❯❯ country optional |
Customer’s billing country |
| ❯❯ phone_number optional |
Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ allow_blank_name optional |
true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date optional |
true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date optional |
true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_response | A hash containing normalized fields from various gateways. Please see our normalized response field documentation for more info |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ gateway_type | The gateway used for this transaction. |
| ❯ gateway_token | The key of the gateway used for this transaction. |
| ❯ workflow_key | The key of the workflow used for this transaction. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Payment Method Token Authorize
POST /v1/transactions/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56G9BCQSC78W5V70JSNFNCFZR0",
"amount": 100,
"currency_code": "USD",
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q"
}
}
<transaction>
<payment_method_token>56G9BCQSC78W5V70JSNFNCFZR0</payment_method_token>
<amount>100</amount>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-07-02T19:13:39Z",
"updated_at": "2024-07-02T19:13:40Z",
"succeeded": true,
"state": "succeeded",
"token": "3t2AjIFBeLvGSqPjZapES3L3R29",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_transaction_id": "9pxg3xqt",
"sub_merchant_key": null,
"gateway_latency_ms": 689,
"warning": null,
"application_id": "Spreedly_BT",
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"gateway_response": {
"card_metadata": {
"issuer_country": "Unknown",
"card_type": "Unknown"
},
"merchant_data": {
"fraud_result": "Approve"
},
"raw_payment_outcome_data": {
"authorization_code": "5TYVK6",
"network_transaction_id": "020240702191340"
}
},
"amount": 100,
"local_amount": null,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"populate_mit_fields": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "21SZ6WB2MN8E7TSQJHMB8G8RCB",
"gateway_type": "braintree",
"response": {
"success": true,
"message": "1000 Approved",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "I",
"cvv_message": "",
"pending": false,
"result_unknown": false,
"error_code": "1000",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-07-02T19:13:40Z",
"updated_at": "2024-07-02T19:13:40Z",
"network_transaction_id": "020240702191340"
},
"shipping_address": {
"name": "Joe Jones",
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313"
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "56G9BCQSC78W5V70JSNFNCFZR0",
"created_at": "2024-07-02T19:12:59.024Z",
"updated_at": "2024-07-02T19:13:39.529Z",
"email": "joey@example.com",
"data": null,
"storage_state": "retained",
"test": true,
"metadata": {
"another_key": 123,
"final_key": true,
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Jones",
"month": 1,
"year": 2029,
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313",
"company": "Acme Inc.",
"full_name": "Joe Jones",
"eligible_for_card_updater": true,
"shipping_address1": "33 Lane Road",
"shipping_address2": "Apartment 4",
"shipping_city": "Wanaque",
"shipping_state": "NJ",
"shipping_zip": "31331",
"shipping_country": "US",
"shipping_phone_number": "919.331.3313",
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"bin_metadata": {
"card_brand": "VISA",
"issuing_bank": "CONOTOXIA SP. Z O.O",
"card_type": "DEBIT",
"card_category": "CLASSIC",
"issuing_country_iso_number": "616",
"issuing_bank_website": null,
"issuing_bank_phone_number": null,
"max_pan_length": 16,
"bin_type": "PERSONAL",
"regulated": "N"
},
"payment_method_type": "credit_card",
"stored_credential_usage": {
"braintree": {
"original_network_transaction_id": "020240702191336",
"network_transaction_id": "020240702191340"
},
"scheme_issued": {
"original_network_transaction_id": "020240702191336",
"network_transaction_id": "020240702191340"
}
},
"errors": [
],
"fingerprint": "56168f5bde6c0454f65eb6ccfc4ff4c3b80e",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2024-07-02T19:13:36Z</created_at>
<updated_at type="dateTime">2024-07-02T19:13:37Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>9t8JYO0m1qUTY7FvF0WV0AwN7qz</token>
<transaction_type>Authorization</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<merchant_profile_key nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_transaction_id>8x9j1jgv</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">487</gateway_latency_ms>
<warning nil="true"/>
<application_id>Spreedly_BT</application_id>
<risk_data nil="true"/>
<merchant_metadata nil="true"/>
<customer_data nil="true"/>
<order_data nil="true"/>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<gateway_response>
<card_metadata>
<issuer_country>Unknown</issuer_country>
<card_type>Unknown</card_type>
</card_metadata>
<merchant_data>
<fraud_result>Not Evaluated</fraud_result>
</merchant_data>
<raw_payment_outcome_data>
<authorization_code>D04Q37</authorization_code>
<network_transaction_id>020240702191336</network_transaction_id>
</raw_payment_outcome_data>
</gateway_response>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<populate_mit_fields type="boolean">false</populate_mit_fields>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>21SZ6WB2MN8E7TSQJHMB8G8RCB</gateway_token>
<gateway_type>braintree</gateway_type>
<shipping_address>
<name>Joe Jones</name>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>1000 Approved</message>
<avs_code>I</avs_code>
<avs_message>Address not verified.</avs_message>
<cvv_code>M</cvv_code>
<cvv_message></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code>1000</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2024-07-02T19:13:36Z</created_at>
<updated_at type="dateTime">2024-07-02T19:13:37Z</updated_at>
<network_transaction_id>020240702191336</network_transaction_id>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>56G9BCQSC78W5V70JSNFNCFZR0</token>
<created_at>2024-07-02T19:12:59.024Z</created_at>
<updated_at>2024-07-02T19:12:59.203Z</updated_at>
<email>joey@example.com</email>
<data nil="true"/>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<another_key type="integer">123</another_key>
<final_key type="boolean">true</final_key>
<key>string value</key>
</metadata>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joe</first_name>
<last_name>Jones</last_name>
<month type="integer">1</month>
<year type="integer">2029</year>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
<company>Acme Inc.</company>
<full_name>Joe Jones</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1>33 Lane Road</shipping_address1>
<shipping_address2>Apartment 4</shipping_address2>
<shipping_city>Wanaque</shipping_city>
<shipping_state>NJ</shipping_state>
<shipping_zip>31331</shipping_zip>
<shipping_country>US</shipping_country>
<shipping_phone_number>919.331.3313</shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<bin_metadata>
<card_brand>VISA</card_brand>
<issuing_bank>CONOTOXIA SP. Z O.O</issuing_bank>
<card_type>DEBIT</card_type>
<card_category>CLASSIC</card_category>
<issuing_country_iso_number>616</issuing_country_iso_number>
<issuing_bank_website nil="true"/>
<issuing_bank_phone_number nil="true"/>
<max_pan_length type="integer">16</max_pan_length>
<bin_type>PERSONAL</bin_type>
<regulated>N</regulated>
</bin_metadata>
<fingerprint>56168f5bde6c0454f65eb6ccfc4ff4c3b80e</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Charge a Payment Method Token (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. No funds are taken with an authorize – a follow-up capture transaction is required to actually move the funds.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ stored_credential_initiator optional |
Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type optional |
What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ stored_credential_alternate_gateway optional |
String containing a specific gateway type or “scheme_issued”. Indicates which NTID to use if first time transacting on a gateway type. |
| ❯ workflow_key optional |
The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment’s default workflow_key if no value is provided |
| ❯ risk_data optional |
Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ merchant_metadata optional |
Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ customer_data optional |
Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_data optional |
Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_id optional |
The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description optional |
A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ ip optional |
The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| ❯ email optional |
Override the customer email address associated with the payment method for this transaction |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address optional |
Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name optional |
Customer’s name in the shipping address |
| ❯❯ address1 optional |
Customer’s shipping address, line 1 |
| ❯❯ address2 optional |
Customer’s shipping address, line 2 |
| ❯❯ city optional |
Customer’s shipping city |
| ❯❯ state optional |
Customer’s shipping state/province |
| ❯❯ zip optional |
Customer’s shipping zip |
| ❯❯ country optional |
Customer’s shipping country |
| ❯❯ phone_number optional |
Customer’s shipping phone |
| ❯ billing_address optional |
Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name optional |
Customer’s name in the billing address |
| ❯❯ address1 optional |
Customer’s billing address, line 1 |
| ❯❯ address2 optional |
Customer’s billing address, line 2 |
| ❯❯ city optional |
Customer’s billing city |
| ❯❯ state optional |
Customer’s billing state/province |
| ❯❯ zip optional |
Customer’s billing zip |
| ❯❯ country optional |
Customer’s billing country |
| ❯❯ phone_number optional |
Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ allow_blank_name optional |
true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date optional |
true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date optional |
true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_response | A hash containing normalized fields from various gateways. Please see our normalized response field documentation for more info |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ gateway_type | The gateway used for this transaction. |
| ❯ gateway_token | The key of the gateway used for this transaction. |
| ❯ workflow_key | The key of the workflow used for this transaction. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Pass-in credit card Purchase
POST /v1/transactions/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"credit_card": {
"first_name": "Joe",
"last_name": "Smith",
"number": "4111111111111111",
"verification_value": "123",
"month": "12",
"year": "2029"
},
"amount": 100,
"currency_code": "USD",
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"transaction_metadata": {
"risk": "low",
"type": "standard"
}
}
}
<transaction>
<credit_card>
<first_name>Joe</first_name>
<last_name>Smith</last_name>
<number>4111111111111111</number>
<verification_value>123</verification_value>
<month>12</month>
<year>2029</year>
</credit_card>
<amount>100</amount>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<currency_code>USD</currency_code>
<transaction_metadata>
<risk>low</risk>
<type>standard</type>
</transaction_metadata>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-07-02T19:07:48Z",
"updated_at": "2024-07-02T19:07:49Z",
"succeeded": true,
"state": "succeeded",
"token": "3P8y4b8oPVhhYvwuxNHLqIuObd0",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_transaction_id": "qh7vrqjt",
"sub_merchant_key": null,
"gateway_latency_ms": 1052,
"warning": null,
"application_id": "Spreedly_BT",
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"gateway_response": {
"card_metadata": {
"issuer_country": "Unknown",
"card_type": "Unknown"
},
"merchant_data": {
"fraud_result": "Approve"
},
"raw_payment_outcome_data": {
"authorization_code": "643SBL",
"network_transaction_id": "020240702190749"
}
},
"amount": 100,
"local_amount": null,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"smart_routed": false,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"populate_mit_fields": false,
"transaction_metadata": {
"risk": "low",
"type": "standard"
},
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "21SZ6WB2MN8E7TSQJHMB8G8RCB",
"gateway_type": "braintree",
"response": {
"success": true,
"message": "1000 Approved",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "M",
"cvv_message": "",
"pending": false,
"result_unknown": false,
"error_code": "1000",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-07-02T19:07:49Z",
"updated_at": "2024-07-02T19:07:49Z",
"network_transaction_id": "020240702190749"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1F3Z9AWA6Z9H5SHE196SZRQJYH",
"created_at": "2024-07-02T19:07:48.227Z",
"updated_at": "2024-07-02T19:07:48.227Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Smith",
"month": 12,
"year": 2029,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Joe Smith",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"bin_metadata": {
"card_brand": "VISA",
"issuing_bank": "CONOTOXIA SP. Z O.O",
"card_type": "DEBIT",
"card_category": "CLASSIC",
"issuing_country_iso_number": "616",
"issuing_bank_website": null,
"issuing_bank_phone_number": null,
"max_pan_length": 16,
"bin_type": "PERSONAL",
"regulated": "N"
},
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "56168f5bde6c0454f65eb6ccfc4ff4c3b80e",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2024-07-02T19:07:46Z</created_at>
<updated_at type="dateTime">2024-07-02T19:07:47Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>13rQv0AkmWwi98NHkRsiFBATT2</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<merchant_profile_key nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_transaction_id>5xh650sg</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">809</gateway_latency_ms>
<warning nil="true"/>
<application_id>Spreedly_BT</application_id>
<risk_data nil="true"/>
<merchant_metadata nil="true"/>
<customer_data nil="true"/>
<order_data nil="true"/>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<gateway_response>
<card_metadata>
<issuer_country>Unknown</issuer_country>
<card_type>Unknown</card_type>
</card_metadata>
<merchant_data>
<fraud_result>Approve</fraud_result>
</merchant_data>
<raw_payment_outcome_data>
<authorization_code>4CF8HZ</authorization_code>
<network_transaction_id>020240702190747</network_transaction_id>
</raw_payment_outcome_data>
</gateway_response>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<populate_mit_fields type="boolean">false</populate_mit_fields>
<transaction_metadata>
<risk>low</risk>
<type>standard</type>
</transaction_metadata>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>21SZ6WB2MN8E7TSQJHMB8G8RCB</gateway_token>
<gateway_type>braintree</gateway_type>
<shipping_address>
<name nil="true"/>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>1000 Approved</message>
<avs_code>I</avs_code>
<avs_message>Address not verified.</avs_message>
<cvv_code>M</cvv_code>
<cvv_message></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code>1000</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2024-07-02T19:07:47Z</created_at>
<updated_at type="dateTime">2024-07-02T19:07:47Z</updated_at>
<network_transaction_id>020240702190747</network_transaction_id>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1X9PDEM9539FFRWHPJ7T1ZDZ1H</token>
<created_at>2024-07-02T19:07:46.722Z</created_at>
<updated_at>2024-07-02T19:07:46.722Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joe</first_name>
<last_name>Smith</last_name>
<month type="integer">12</month>
<year type="integer">2029</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Joe Smith</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<bin_metadata>
<card_brand>VISA</card_brand>
<issuing_bank>CONOTOXIA SP. Z O.O</issuing_bank>
<card_type>DEBIT</card_type>
<card_category>CLASSIC</card_category>
<issuing_country_iso_number>616</issuing_country_iso_number>
<issuing_bank_website nil="true"/>
<issuing_bank_phone_number nil="true"/>
<max_pan_length type="integer">16</max_pan_length>
<bin_type>PERSONAL</bin_type>
<regulated>N</regulated>
</bin_metadata>
<fingerprint>56168f5bde6c0454f65eb6ccfc4ff4c3b80e</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Pass a credit card payment method directly into the purchase request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway to charge for a specified amount
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ credit_card | Credit card element |
| ❯❯ first_name required |
The first name of the cardholder |
| ❯❯ last_name required |
The last name of the cardholder |
| ❯❯ number required |
The full card number |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
| ❯❯ month required |
The expiration month of the card |
| ❯❯ year required |
The expiration year of the card |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the cardholder. If provided, will be parsed to determine first_name and last_name. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ stored_credential_initiator optional |
Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type optional |
What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ stored_credential_alternate_gateway optional |
String containing a specific gateway type or “scheme_issued”. Indicates which NTID to use if first time transacting on a gateway type. |
| ❯ workflow_key optional |
The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment’s default workflow_key if no value is provided |
| ❯ risk_data optional |
Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ merchant_metadata optional |
Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ customer_data optional |
Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_data optional |
Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_id optional |
The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description optional |
A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ ip optional |
The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| ❯ email optional |
Override the customer email address associated with the payment method for this transaction |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address optional |
Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name optional |
Customer’s name in the shipping address |
| ❯❯ address1 optional |
Customer’s shipping address, line 1 |
| ❯❯ address2 optional |
Customer’s shipping address, line 2 |
| ❯❯ city optional |
Customer’s shipping city |
| ❯❯ state optional |
Customer’s shipping state/province |
| ❯❯ zip optional |
Customer’s shipping zip |
| ❯❯ country optional |
Customer’s shipping country |
| ❯❯ phone_number optional |
Customer’s shipping phone |
| ❯ billing_address optional |
Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name optional |
Customer’s name in the billing address |
| ❯❯ address1 optional |
Customer’s billing address, line 1 |
| ❯❯ address2 optional |
Customer’s billing address, line 2 |
| ❯❯ city optional |
Customer’s billing city |
| ❯❯ state optional |
Customer’s billing state/province |
| ❯❯ zip optional |
Customer’s billing zip |
| ❯❯ country optional |
Customer’s billing country |
| ❯❯ phone_number optional |
Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ allow_blank_name optional |
true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date optional |
true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date optional |
true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_response | A hash containing normalized fields from various gateways. Please see our normalized response field documentation for more info |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ gateway_type | The gateway used for this transaction. |
| ❯ gateway_token | The key of the gateway used for this transaction. |
| ❯ workflow_key | The key of the workflow used for this transaction. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Payment Method Token Purchase
POST /v1/transactions/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56G9BCQSC78W5V70JSNFNCFZR0",
"amount": 100,
"currency_code": "USD",
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q"
}
}
<transaction>
<payment_method_token>56G9BCQSC78W5V70JSNFNCFZR0</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-07-02T19:13:39Z",
"updated_at": "2024-07-02T19:13:40Z",
"succeeded": true,
"state": "succeeded",
"token": "3t2AjIFBeLvGSqPjZapES3L3R29",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_transaction_id": "9pxg3xqt",
"sub_merchant_key": null,
"gateway_latency_ms": 689,
"warning": null,
"application_id": "Spreedly_BT",
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": "01HV4PEM4FZW5N0KY0T8AYTC2Q",
"gateway_response": {
"card_metadata": {
"issuer_country": "Unknown",
"card_type": "Unknown"
},
"merchant_data": {
"fraud_result": "Approve"
},
"raw_payment_outcome_data": {
"authorization_code": "5TYVK6",
"network_transaction_id": "020240702191340"
}
},
"amount": 100,
"local_amount": null,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"populate_mit_fields": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "21SZ6WB2MN8E7TSQJHMB8G8RCB",
"gateway_type": "braintree",
"response": {
"success": true,
"message": "1000 Approved",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "I",
"cvv_message": "",
"pending": false,
"result_unknown": false,
"error_code": "1000",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-07-02T19:13:40Z",
"updated_at": "2024-07-02T19:13:40Z",
"network_transaction_id": "020240702191340"
},
"shipping_address": {
"name": "Joe Jones",
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313"
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "56G9BCQSC78W5V70JSNFNCFZR0",
"created_at": "2024-07-02T19:12:59.024Z",
"updated_at": "2024-07-02T19:13:39.529Z",
"email": "joey@example.com",
"data": null,
"storage_state": "retained",
"test": true,
"metadata": {
"another_key": 123,
"final_key": true,
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Jones",
"month": 1,
"year": 2029,
"address1": "33 Lane Road",
"address2": "Apartment 4",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": "919.331.3313",
"company": "Acme Inc.",
"full_name": "Joe Jones",
"eligible_for_card_updater": true,
"shipping_address1": "33 Lane Road",
"shipping_address2": "Apartment 4",
"shipping_city": "Wanaque",
"shipping_state": "NJ",
"shipping_zip": "31331",
"shipping_country": "US",
"shipping_phone_number": "919.331.3313",
"issuer_identification_number": "41111111",
"click_to_pay": false,
"managed": true,
"bin_metadata": {
"card_brand": "VISA",
"issuing_bank": "CONOTOXIA SP. Z O.O",
"card_type": "DEBIT",
"card_category": "CLASSIC",
"issuing_country_iso_number": "616",
"issuing_bank_website": null,
"issuing_bank_phone_number": null,
"max_pan_length": 16,
"bin_type": "PERSONAL",
"regulated": "N"
},
"payment_method_type": "credit_card",
"stored_credential_usage": {
"braintree": {
"original_network_transaction_id": "020240702191336",
"network_transaction_id": "020240702191340"
},
"scheme_issued": {
"original_network_transaction_id": "020240702191336",
"network_transaction_id": "020240702191340"
}
},
"errors": [
],
"fingerprint": "56168f5bde6c0454f65eb6ccfc4ff4c3b80e",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2024-07-02T19:13:38Z</created_at>
<updated_at type="dateTime">2024-07-02T19:13:39Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>TU2aFmPhvE5tzqoBHD78vQhONhR</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<merchant_profile_key nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_transaction_id>fa92mc8k</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">850</gateway_latency_ms>
<warning nil="true"/>
<application_id>Spreedly_BT</application_id>
<risk_data nil="true"/>
<merchant_metadata nil="true"/>
<customer_data nil="true"/>
<order_data nil="true"/>
<workflow_key>01HV4PEM4FZW5N0KY0T8AYTC2Q</workflow_key>
<gateway_response>
<card_metadata>
<issuer_country>Unknown</issuer_country>
<card_type>Unknown</card_type>
</card_metadata>
<merchant_data>
<fraud_result>Approve</fraud_result>
</merchant_data>
<raw_payment_outcome_data>
<authorization_code>53DL9Q</authorization_code>
<network_transaction_id>020240702191339</network_transaction_id>
</raw_payment_outcome_data>
</gateway_response>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<populate_mit_fields type="boolean">false</populate_mit_fields>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>21SZ6WB2MN8E7TSQJHMB8G8RCB</gateway_token>
<gateway_type>braintree</gateway_type>
<shipping_address>
<name>Joe Jones</name>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>1000 Approved</message>
<avs_code>I</avs_code>
<avs_message>Address not verified.</avs_message>
<cvv_code>I</cvv_code>
<cvv_message></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code>1000</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2024-07-02T19:13:39Z</created_at>
<updated_at type="dateTime">2024-07-02T19:13:39Z</updated_at>
<network_transaction_id>020240702191339</network_transaction_id>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>56G9BCQSC78W5V70JSNFNCFZR0</token>
<created_at>2024-07-02T19:12:59.024Z</created_at>
<updated_at>2024-07-02T19:13:38.218Z</updated_at>
<email>joey@example.com</email>
<data nil="true"/>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<another_key type="integer">123</another_key>
<final_key type="boolean">true</final_key>
<key>string value</key>
</metadata>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joe</first_name>
<last_name>Jones</last_name>
<month type="integer">1</month>
<year type="integer">2029</year>
<address1>33 Lane Road</address1>
<address2>Apartment 4</address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number>919.331.3313</phone_number>
<company>Acme Inc.</company>
<full_name>Joe Jones</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1>33 Lane Road</shipping_address1>
<shipping_address2>Apartment 4</shipping_address2>
<shipping_city>Wanaque</shipping_city>
<shipping_state>NJ</shipping_state>
<shipping_zip>31331</shipping_zip>
<shipping_country>US</shipping_country>
<shipping_phone_number>919.331.3313</shipping_phone_number>
<issuer_identification_number>41111111</issuer_identification_number>
<click_to_pay type="boolean">false</click_to_pay>
<managed type="boolean">true</managed>
<payment_method_type>credit_card</payment_method_type>
<stored_credential_usage>
<braintree>
<original_network_transaction_id>020240702191336</original_network_transaction_id>
<network_transaction_id>020240702191339</network_transaction_id>
</braintree>
<scheme_issued>
<original_network_transaction_id>020240702191336</original_network_transaction_id>
<network_transaction_id>020240702191339</network_transaction_id>
</scheme_issued>
</stored_credential_usage>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<bin_metadata>
<card_brand>VISA</card_brand>
<issuing_bank>CONOTOXIA SP. Z O.O</issuing_bank>
<card_type>DEBIT</card_type>
<card_category>CLASSIC</card_category>
<issuing_country_iso_number>616</issuing_country_iso_number>
<issuing_bank_website nil="true"/>
<issuing_bank_phone_number nil="true"/>
<max_pan_length type="integer">16</max_pan_length>
<bin_type>PERSONAL</bin_type>
<regulated>N</regulated>
</bin_metadata>
<fingerprint>56168f5bde6c0454f65eb6ccfc4ff4c3b80e</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Charge a Payment Method Token (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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ stored_credential_initiator optional |
Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type optional |
What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ stored_credential_alternate_gateway optional |
String containing a specific gateway type or “scheme_issued”. Indicates which NTID to use if first time transacting on a gateway type. |
| ❯ workflow_key optional |
The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment’s default workflow_key if no value is provided |
| ❯ risk_data optional |
Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ merchant_metadata optional |
Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ customer_data optional |
Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_data optional |
Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our normalized request guide for more info. |
| ❯ order_id optional |
The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description optional |
A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ ip optional |
The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| ❯ email optional |
Override the customer email address associated with the payment method for this transaction |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address optional |
Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name optional |
Customer’s name in the shipping address |
| ❯❯ address1 optional |
Customer’s shipping address, line 1 |
| ❯❯ address2 optional |
Customer’s shipping address, line 2 |
| ❯❯ city optional |
Customer’s shipping city |
| ❯❯ state optional |
Customer’s shipping state/province |
| ❯❯ zip optional |
Customer’s shipping zip |
| ❯❯ country optional |
Customer’s shipping country |
| ❯❯ phone_number optional |
Customer’s shipping phone |
| ❯ billing_address optional |
Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name optional |
Customer’s name in the billing address |
| ❯❯ address1 optional |
Customer’s billing address, line 1 |
| ❯❯ address2 optional |
Customer’s billing address, line 2 |
| ❯❯ city optional |
Customer’s billing city |
| ❯❯ state optional |
Customer’s billing state/province |
| ❯❯ zip optional |
Customer’s billing zip |
| ❯❯ country optional |
Customer’s billing country |
| ❯❯ phone_number optional |
Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ allow_blank_name optional |
true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date optional |
true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date optional |
true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_response | A hash containing normalized fields from various gateways. Please see our normalized response field documentation for more info |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ gateway_type | The gateway used for this transaction. |
| ❯ gateway_token | The key of the gateway used for this transaction. |
| ❯ workflow_key | The key of the workflow used for this transaction. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Purchase
Charge a payment method a specific amount at the target gateway.
Payment Method Token
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:01:46Z",
"updated_at": "2018-11-07T15:01:46Z",
"succeeded": true,
"state": "succeeded",
"token": "NNLCRXoNV631SlcCLyh9uUVr8PA",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "68",
"gateway_latency_ms": 23,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:01:46Z",
"updated_at": "2018-11-07T15:01:46Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2018-11-07T15:01:45Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:01:45Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:45Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>E2h3WOyL3rGgnj7IqtcMwCNJMn4</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>58</gateway_transaction_id>
<gateway_latency_ms type="integer">27</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-11-07T15:01:45Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:45Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:45Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
<another_key type="integer">123</another_key>
<final_key type="boolean">true</final_key>
</metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Charge a Payment Method Token (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.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ ignore_failed_authentication_result | Complete 3DS2 Global transaction when authentication fails. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
SCA Authenticated
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"sca_authentication_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<sca_authentication_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</sca_authentication_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK Created
{
"transaction": {
"on_test_gateway": false,
"created_at": "2020-11-12T15:28:15Z",
"updated_at": "2020-11-12T15:28:16Z",
"succeeded": false,
"state": "pending",
"token": "VvplgnvtAWAoa38801a7e24qAHI",
"transaction_type": "Authorize",
"order_id": null,
"ip": "127.0.0.1",
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": null,
"gateway_latency_ms": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"sub_merchant_key": null,
"warning": null,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2020-11-10T19:38:14Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
},
"sca_authentication": {
"created_at": "2020-11-12T15:28:15Z",
"updated_at": "2020-11-12T15:28:16Z",
"succeeded": true,
"state": "succeeded",
"token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"flow_performed": "challenge",
"message": null,
"sca_provider_key": "6JXUReoA9KgnYoSchcJU0OAA6N0",
"three_ds_version": "2.2.0",
"ecommerce_indicator": null,
"authentication_value": null,
"directory_server_transaction_id": "5c06e665-3675-494e-9ccf-cc078ebd8dc9",
"authentication_value_algorithm": null,
"directory_response_status": "C",
"authentication_response_status": "C",
"required_action": "challenge",
"acs_reference_number": null,
"acs_rendering_type": null,
"acs_signed_content": null,
"acs_transaction_id": null,
"sdk_transaction_id": null,
"challenge_form": "<form action=\"https://testds3.seglan.com/server/authentication/load\" method=\"POST\">\n <input name=\"browserChallengeToken\" value=\"b3055a53-7c4d-4f71-bb33-742af0daa96f\" type=\"hidden\"/>\n</form>",
"challenge_form_embed_url": null,
"three_ds_server_trans_id": "b3055a53-7c4d-4f71-bb33-742af0daa96f",
"xid": null,
"enrolled": null,
"transaction_type": "Sca::Authentication"
}
}
}
<transaction>
<on_test_gateway type="boolean">false</on_test_gateway>
<created_at type="dateTime">2020-11-12T15:10:37Z</created_at>
<updated_at type="dateTime">2020-11-12T15:10:38Z</updated_at>
<succeeded type="boolean">false</succeeded>
<state>pending</state>
<token>X3WSJdOofHm4tJL84l3ZW8dtDal</token>
<transaction_type>Authorize</transaction_type>
<order_id nil="true"></order_id>
<ip>127.0.0.1</ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id nil="true"></gateway_transaction_id>
<gateway_latency_ms nil="true"></gateway_latency_ms>
<stored_credential_initiator nil="true"></stored_credential_initiator>
<stored_credential_reason_type nil="true"></stored_credential_reason_type>
<warning nil="true"></warning>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<message key="messages.transaction_pending">Pending</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2020-11-10T19:38:14Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<sca_authentication>
<created_at type="dateTime">2020-11-12T15:10:37Z</created_at>
<updated_at type="dateTime">2020-11-12T15:10:38Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>56wyNnSmuA6CWYP7w0MiYCVIbW6</token>
<flow_performed>challenge</flow_performed>
<message nil="true"></message>
<sca_provider_key>6JXUReoA9KgnYoSchcJU0OAA6N0</sca_provider_key>
<three_ds_version>2.2.0</three_ds_version>
<ecommerce_indicator nil="true"></ecommerce_indicator>
<authentication_value nil="true"></authentication_value>
<directory_server_transaction_id>b307301e-5ddc-476e-b4da-586327cfe9e9</directory_server_transaction_id>
<authentication_value_algorithm nil="true"></authentication_value_algorithm>
<directory_response_status>C</directory_response_status>
<authentication_response_status>C</authentication_response_status>
<required_action>challenge</required_action>
<acs_reference_number nil="true"></acs_reference_number>
<acs_rendering_type nil="true"></acs_rendering_type>
<acs_signed_content nil="true"></acs_signed_content>
<acs_transaction_id nil="true"></acs_transaction_id>
<sdk_transaction_id nil="true"></sdk_transaction_id>
<challenge_form><form action="https://testds3.seglan.com/server/authentication/load" method="POST">
<input name="browserChallengeToken" value="116e1940-c712-4b78-9f2c-0a6f976184d7" type="hidden"/>
</form></challenge_form>
<challenge_form_embed_url nil="true"></challenge_form_embed_url>
<three_ds_server_trans_id>116e1940-c712-4b78-9f2c-0a6f976184d7</three_ds_server_trans_id>
<xid nil="true"></xid>
<enrolled nil="true"></enrolled>
<transaction_type>Sca::Authentication</transaction_type>
</sca_authentication>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Charge an SCA Authenticated payment method (already stored in the Spreedly environment) the specified amount.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ sca_authentication_token required |
The token received in response body of SCA Authenticate endpoint when performing an SCA Authentication on a specified payment method. See instructions to obtain |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
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.
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in credit card
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"credit_card": {
"first_name": "Joe",
"last_name": "Smith",
"number": "4111111111111111",
"verification_value": "123",
"month": "12",
"year": "2029"
},
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<credit_card>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<number>4111111111111111</number>
<verification_value>423</verification_value>
<month>3</month>
<year>2029</year>
</credit_card>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:01:45Z",
"updated_at": "2018-11-07T15:01:45Z",
"succeeded": true,
"state": "succeeded",
"token": "a8CseM5RdIhHQwsgCKTZLi9UhSo",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "49",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:01:45Z",
"updated_at": "2018-11-07T15:01:45Z"
},
"shipping_address": {
"name": "Joe Smith",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "ZjcXez8r5tOkQ4wjXDCv5lZ6pKg",
"created_at": "2018-11-07T15:01:45Z",
"updated_at": "2018-11-07T15:01:45Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Smith",
"month": 12,
"year": 2018,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Joe Smith",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:01:44Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:44Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>HlOybss40Zr3hwCqqwRKBlYmXsi</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>47</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Joey Jones</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-11-07T15:01:44Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:44Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>TtdNEGumPZzS7RWBiwj4ejLpHbd</token>
<created_at type="dateTime">2018-11-07T15:01:44Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:44Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<month type="integer">3</month>
<year type="integer">2020</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Joey Jones</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Pass a credit card payment method directly into the purchase request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ credit_card | Credit card element |
| ❯❯ first_name required |
The first name of the cardholder |
| ❯❯ last_name required |
The last name of the cardholder |
| ❯❯ number required |
The full card number |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
| ❯❯ month required |
The expiration month of the card |
| ❯❯ year required |
The expiration year of the card |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the cardholder. If provided, will be parsed to determine first_name and last_name. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ ignore_failed_authentication_result | Complete 3DS2 Global transaction when authentication fails. |
| ❯ allow_blank_name | true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date | true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date | true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in bank account/ACH
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"bank_account": {
"first_name": "Joe",
"last_name": "Smith",
"bank_routing_number": "021000021",
"bank_account_number": "9876543210"
},
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<bank_account>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<bank_routing_number>021000021</bank_routing_number>
<bank_account_number>9876543210</bank_account_number>
</bank_account>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:01:46Z",
"updated_at": "2018-11-07T15:01:47Z",
"succeeded": true,
"state": "succeeded",
"token": "XE7NblVFR53IT5Hw7VGZz9i5t1g",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "51",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:01:47Z",
"updated_at": "2018-11-07T15:01:47Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "DqyNuFCg3EnufBB3nAyqKQTVPFO",
"created_at": "2018-11-07T15:01:46Z",
"updated_at": "2018-11-07T15:01:46Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"full_name": "Joe Smith",
"bank_name": null,
"account_type": null,
"account_holder_type": null,
"routing_number_display_digits": "021",
"account_number_display_digits": "3210",
"first_name": "Joe",
"last_name": "Smith",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"payment_method_type": "bank_account",
"errors": [
],
"routing_number": "021*",
"account_number": "*3210"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:01:46Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:46Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>UtJCx0FQIr82iswk7egOJgsFLHr</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>57</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name nil="true"/>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-11-07T15:01:46Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:46Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>LBDgxfdj98Rgq0nsmDPxdUfafWk</token>
<created_at type="dateTime">2018-11-07T15:01:46Z</created_at>
<updated_at type="dateTime">2018-11-07T15:01:46Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<full_name>Joey Jones</full_name>
<bank_name nil="true"/>
<account_type nil="true"/>
<account_holder_type nil="true"/>
<routing_number_display_digits>021</routing_number_display_digits>
<account_number_display_digits>3210</account_number_display_digits>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<payment_method_type>bank_account</payment_method_type>
<errors>
</errors>
<routing_number>021*</routing_number>
<account_number>*3210</account_number>
</payment_method>
</transaction>
Pass a bank account/ACH payment method directly into the purchase request. If the bank account is valid, it will automatically be tokenized at Spreedly before sending to the gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ bank_account | Bank account element |
| ❯❯ first_name required |
The first name of the account owner |
| ❯❯ last_name required |
The last name of the account owner |
| ❯❯ bank_routing_number required |
The account routing number |
| ❯❯ bank_account_number required |
The account number |
| ❯❯ bank_name | The name of the bank |
| ❯❯ bank_account_type | The type of account. Can be one of checking or savings. |
| ❯❯ bank_account_holder_type | The account holder type. Can be one business or personal. |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the account owner. If provided, will be parsed to determine first_name and last_name. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in Apple Pay
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"apple_pay": {
"payment_data": {
"version": "EC_v1",
"data": "QlzLxRFnNP9/GTaMhBwgmZ2ywntbr9iOcBY4TjPZyNrnCwsJd2cq61bDQjo3agVU0LuEot2VIHHocVrp5jdy0FkxdFhGd+j7hPvutFYGwZPcuuBgROb0beA1wfGDi09I+OWL+8x5+8QPl+y8EAGJdWHXr4CuL7hEj4CjtUhfj5GYLMceUcvwgGaWY7WzqnEO9UwUowlDP9C3cD21cW8osn/IKROTInGcZB0mzM5bVHM73NSFiFepNL6rQtomp034C+p9mikB4nc+vR49oVop0Pf+uO7YVq7cIWrrpgMG7ussnc3u4bmr3JhCNtKZzRQ2MqTxKv/CfDq099JQIvTj8hbqswv1t+yQ5ZhJ3m4bcPwrcyIVej5J241R7dNPu9xVjM6LSOX9KeGZQGud",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTUwMjI0MTgzNTU5WjAvBgkqhkiG9w0BCQQxIgQgohbm8d0A42OAyMnc5fsgQoCNYjtEd/W/dW6+yezIwoAwCgYIKoZIzj0EAwIERzBFAiEAtEkap+JHypwfL1EdabD7RWPZol3na0LhMk9XzLhis0oCIGwxzOhQnMw+Td8WglTMNYcidqeYILTGzn3zMEXmW3j7AAAAAAAA",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQwjaSlnZ3EXpwKfWAd2e1VnbS6vmioMyF6bNcq/Qd65NLQsjrPatzHWbJzG7v5vJtAyrf6WhoNx3C1VchQxYuw==",
"transactionId": "e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371",
"publicKeyHash": "/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI="
}
},
"test_card_number": "4111111111111111"
}
}
}
<transaction>
<apple_pay>
<payment_data>
<![CDATA[{"version":"EC_v1","data":"QlzLxRFnNP9/GTaMhBwgmZ2ywntbr9iOcBY4TjPZyNrnCwsJd2cq61bDQjo3agVU0LuEot2VIHHocVrp5jdy0FkxdFhGd+j7hPvutFYGwZPcuuBgROb0beA1wfGDi09I+OWL+8x5+8QPl+y8EAGJdWHXr4CuL7hEj4CjtUhfj5GYLMceUcvwgGaWY7WzqnEO9UwUowlDP9C3cD21cW8osn/IKROTInGcZB0mzM5bVHM73NSFiFepNL6rQtomp034C+p9mikB4nc+vR49oVop0Pf+uO7YVq7cIWrrpgMG7ussnc3u4bmr3JhCNtKZzRQ2MqTxKv/CfDq099JQIvTj8hbqswv1t+yQ5ZhJ3m4bcPwrcyIVej5J241R7dNPu9xVjM6LSOX9KeGZQGud","signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTUwMjI0MTgzNTU5WjAvBgkqhkiG9w0BCQQxIgQgohbm8d0A42OAyMnc5fsgQoCNYjtEd/W/dW6+yezIwoAwCgYIKoZIzj0EAwIERzBFAiEAtEkap+JHypwfL1EdabD7RWPZol3na0LhMk9XzLhis0oCIGwxzOhQnMw+Td8WglTMNYcidqeYILTGzn3zMEXmW3j7AAAAAAAA","header":{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQwjaSlnZ3EXpwKfWAd2e1VnbS6vmioMyF6bNcq/Qd65NLQsjrPatzHWbJzG7v5vJtAyrf6WhoNx3C1VchQxYuw==","transactionId":"e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371","publicKeyHash":"/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI="}}
]]>
</payment_data>
<test_card_number>4111111111111111</test_card_number>
</apple_pay>
</transaction>
HTTPS/1.1 200 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T15:19:50Z",
"updated_at": "2017-11-21T15:19:50Z",
"succeeded": true,
"state": "succeeded",
"token": "DVRQccX1fYEWERoO7rKuTbSfZpV",
"transaction_type": "Purchase",
"order_id": "e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371",
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "64",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T15:19:50Z",
"updated_at": "2017-11-21T15:19:50Z"
},
"shipping_address": {
"name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "3LxsKu5cCdTPxr5fH3S49HStP9V",
"created_at": "2017-11-21T15:19:50Z",
"updated_at": "2017-11-21T15:19:50Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": null,
"last_name": null,
"month": 3,
"year": 2018,
"full_name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "apple_pay",
"errors": [
]
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T15:19:50Z</created_at>
<updated_at type="dateTime">2017-11-21T15:19:51Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>OGm6S9ZMmBOoJbCy3oEJxVtEsHq</token>
<transaction_type>Purchase</transaction_type>
<order_id>e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371</order_id>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>67</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name></name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2017-11-21T15:19:50Z</created_at>
<updated_at type="dateTime">2017-11-21T15:19:51Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>OoC7r75LfI0YBnQrE0C5udCrXv3</token>
<created_at type="dateTime">2017-11-21T15:19:50Z</created_at>
<updated_at type="dateTime">2017-11-21T15:19:50Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name nil="true"/>
<last_name nil="true"/>
<month type="integer">3</month>
<year type="integer">2018</year>
<full_name></full_name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>apple_pay</payment_method_type>
<errors>
</errors>
</payment_method>
</transaction>
Pass an Apple Pay payment method directly into the purchase request. If the Apple Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ apple_pay | Apple pay element |
| ❯❯ payment_data required |
The JSON serialized paymentData property of an Apple Pay PKPaymentToken |
| ❯❯ test_card_number | Apple Pay does not provide a way to create a test payment token. To mark this as a test Apple Pay payment method, specify a test card number in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Apple Pay payment data. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in Google Pay
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"amount": 1122,
"currency_code": "USD",
"google_pay": {
"payment_data": {
"signature": "MEUCIA6SGVRwhOyeYRkeDUUNwB/kGtyfQAlOsg7NZydT17u/AiEA48BhWGQEF1EbEU0J+m8eSK3rTfhok9QqpiFVbME+Ky0=",
"protocolVersion": "ECv1",
"signedMessage": "{\"encryptedMessage\":\"3v4IcT/eovIDP2WF8iRUy4qWQnE9Cx0vQxIZ5f9i3Emv3Tzs1AzvB7cxXhxrjp9FVIzdOwsZAPAsm03gvoYq8Xdr70XvrVRd2MFwQhMC7IV/uEsthw4JsR8oCkbI5v/zqhu2B+JodFgavNliHcpKBgijy2D6bpx7jXEkM39M/L4oBObFxFrhVSLA1GjOV6A5gLAXNXt0ffkCYekihqAyJrWlk3sCBDCF5SUiAKEIOIZtzZLgusxjVp6ufZHOHm/53uhAi6JWSJ1E6G5aaYGtULYdwgURHtxN5OIzQPYlEGctaQd5tgfCsBFfGkYyN1GRNgclbaLzAfk/Jn7/6IVKuV0ol3xubTcnjGTZXwtTjiEyYDoz1yVqB9ViMmJa55L6nBtbbAkcNEgAi7dPnrbvBGEP7QWsNT9D71g8SWrlRTCYUAOyuamaQhofG4ul1IVjmltdAy2BHBWpqgJnR9kczydQyE7uDiqhSC1/0eG8GCGIqoi8XfOioGXfMyLZ1p2ZcNK9ECjzUrH/edrwgtShxgWuWMwQTM4DQlVTAA/R4DVs192YWZcc7jm5wLqZ0+XEaPuighJM1Ps1Egeccg\\u003d\\u003d\",\"ephemeralPublicKey\":\"BA2SvF9BdCX7Tl1wwRkyLzTfqhctobhZgSugC9Cz77XNUCBOBMfFyJQt506PUs89D6IJZZfOkZopy0shRF9Uph4\\u003d\",\"tag\":\"Uhin1BE7KAuuiam7eEQFimRUDd9Xn6tZc2fClTpfrXQ\\u003d\"}"
},
"test_card_number": "4111111111111111"
}
}
}
<transaction>
<amount>1122</amount>
<currency_code>USD</currency_code>
<google_pay>
<payment_data>
<![CDATA[{"signature":"MEUCIA6SGVRwhOyeYRkeDUUNwB/kGtyfQAlOsg7NZydT17u/AiEA48BhWGQEF1EbEU0J+m8eSK3rTfhok9QqpiFVbME+Ky0\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"3v4IcT/eovIDP2WF8iRUy4qWQnE9Cx0vQxIZ5f9i3Emv3Tzs1AzvB7cxXhxrjp9FVIzdOwsZAPAsm03gvoYq8Xdr70XvrVRd2MFwQhMC7IV/uEsthw4JsR8oCkbI5v/zqhu2B+JodFgavNliHcpKBgijy2D6bpx7jXEkM39M/L4oBObFxFrhVSLA1GjOV6A5gLAXNXt0ffkCYekihqAyJrWlk3sCBDCF5SUiAKEIOIZtzZLgusxjVp6ufZHOHm/53uhAi6JWSJ1E6G5aaYGtULYdwgURHtxN5OIzQPYlEGctaQd5tgfCsBFfGkYyN1GRNgclbaLzAfk/Jn7/6IVKuV0ol3xubTcnjGTZXwtTjiEyYDoz1yVqB9ViMmJa55L6nBtbbAkcNEgAi7dPnrbvBGEP7QWsNT9D71g8SWrlRTCYUAOyuamaQhofG4ul1IVjmltdAy2BHBWpqgJnR9kczydQyE7uDiqhSC1/0eG8GCGIqoi8XfOioGXfMyLZ1p2ZcNK9ECjzUrH/edrwgtShxgWuWMwQTM4DQlVTAA/R4DVs192YWZcc7jm5wLqZ0+XEaPuighJM1Ps1Egeccg\\u003d\\u003d\",\"ephemeralPublicKey\":\"BA2SvF9BdCX7Tl1wwRkyLzTfqhctobhZgSugC9Cz77XNUCBOBMfFyJQt506PUs89D6IJZZfOkZopy0shRF9Uph4\\u003d\",\"tag\":\"Uhin1BE7KAuuiam7eEQFimRUDd9Xn6tZc2fClTpfrXQ\\u003d\"}"}
]]>
</payment_data>
<test_card_number>4111111111111111</test_card_number>
</google_pay>
</transaction>
HTTPS/1.1 200 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-09-25T15:54:59Z",
"updated_at": "2018-09-25T15:54:59Z",
"succeeded": true,
"state": "succeeded",
"token": "DNvqE9lr7rz18prqT5q1PeN3s8Y",
"transaction_type": "Purchase",
"order_id": "AH2EjtcuYvaTXHijJ9TKSJXyBjs-NltywbAVH_-oVmjtctSwWsuU1xWUTqrsamtLM-xs8-c0wQY7t6jd5MmJfMxWca_WKjXIjk6vXr8Zcn-NCftMQwQLN2KmF1_LhgBo_Nm_FXo1plC-",
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "63",
"gateway_latency_ms": 0,
"amount": 1122,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "IRMVoS9jurugLBkX8pM7YTmTj9F",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-09-25T15:54:59Z",
"updated_at": "2018-09-25T15:54:59Z"
},
"shipping_address": {
"name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "aQCdSB3eFwShLgQueSVgfk2D2gX",
"created_at": "2018-09-25T15:54:59Z",
"updated_at": "2018-09-25T15:54:59Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": null,
"last_name": null,
"month": 12,
"year": 2023,
"full_name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "google_pay",
"google_pay_type": "TOKENIZED_CARD",
"errors": [
]
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-09-25T15:54:58Z</created_at>
<updated_at type="dateTime">2018-09-25T15:54:59Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>KogIeHh3hqteA4Wr3VUluvqpiLr</token>
<transaction_type>Purchase</transaction_type>
<order_id>AH2EjtcuYvaTXHijJ9TKSJXyBjs-NltywbAVH_-oVmjtctSwWsuU1xWUTqrsamtLM-xs8-c0wQY7t6jd5MmJfMxWca_WKjXIjk6vXr8Zcn-NCftMQwQLN2KmF1_LhgBo_Nm_FXo1plC-</order_id>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>67</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">1122</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>IRMVoS9jurugLBkX8pM7YTmTj9F</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name></name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-09-25T15:54:58Z</created_at>
<updated_at type="dateTime">2018-09-25T15:54:59Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>22kSyzEL4tKGpUUhNW2BTZNAtsZ</token>
<created_at type="dateTime">2018-09-25T15:54:58Z</created_at>
<updated_at type="dateTime">2018-09-25T15:54:58Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name nil="true"/>
<last_name nil="true"/>
<month type="integer">12</month>
<year type="integer">2023</year>
<full_name></full_name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>google_pay</payment_method_type>
<google_pay_type>TOKENIZED_CARD</google_pay_type>
<errors>
</errors>
</payment_method>
</transaction>
Pass a Google Pay payment method directly into the purchase request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ google_pay | Google Pay element |
| ❯❯ payment_data required |
The JSON-formatted encrypted payload Google Pay Payment Token |
| ❯❯ test_card_number | Specify a test card number in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Google Pay payment data. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Reference purchase
POST /v1/transactions/<transaction_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"amount": 80
}
}
<transaction>
<amount>80</amount>
</transaction>
HTTPS/1.1 200 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T15:26:32Z",
"updated_at": "2017-11-21T15:26:32Z",
"succeeded": true,
"state": "succeeded",
"token": "TvwQDzUDbKsBzMqy8VM98BDVAAD",
"transaction_type": "PurchaseViaReference",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "45",
"gateway_latency_ms": 1,
"amount": 80,
"currency_code": "USD",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T15:26:32Z",
"updated_at": "2017-11-21T15:26:32Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
],
"reference_token": "QlogpjClt4SPFBlpWZajWICgc5p"
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T15:26:33Z</created_at>
<updated_at type="dateTime">2017-11-21T15:26:33Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>UBNCM4x4DKLaKzG23h623gSs98A</token>
<transaction_type>PurchaseViaReference</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>66</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">80</amount>
<currency_code>USD</currency_code>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name nil="true"></name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2017-11-21T15:26:33Z</created_at>
<updated_at type="dateTime">2017-11-21T15:26:33Z</updated_at>
</response>
<api_urls>
</api_urls>
<reference_token>Qyeli2JTwG6MIxnPnjm89jUoCbB</reference_token>
</transaction>
Execute a purchase using the payment method utilized in a previous transaction.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying this transaction at Spreedly |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Authorize
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 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.
Payment Method Token
POST /v1/gateways/<gateway_token>/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:05:08Z",
"updated_at": "2018-11-07T15:05:08Z",
"succeeded": true,
"state": "succeeded",
"token": "3iUAv9hUqP7x0bMxVtQKXlayFx0",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "63",
"gateway_latency_ms": 19,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful authorize",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:05:08Z",
"updated_at": "2018-11-07T15:05:08Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2018-11-07T15:05:07Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:05:07Z</created_at>
<updated_at type="dateTime">2018-11-07T15:05:07Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>OzqbXeWLwgm6qA6ahruhqMjiBN9</token>
<transaction_type>Authorization</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>45</gateway_transaction_id>
<gateway_latency_ms type="integer">18</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful authorize</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-11-07T15:05:07Z</created_at>
<updated_at type="dateTime">2018-11-07T15:05:07Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2018-11-07T15:05:05Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
<another_key type="integer">123</another_key>
<final_key type="boolean">true</final_key>
</metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Authorize a Payment Method Token (already stored in the Spreedly environment) to be charged a specific amount.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ ignore_failed_authentication_result | Complete 3DS2 Global transaction when authentication fails. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
SCA Authenticated
POST /v1/gateways/<gateway_token>/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"sca_authentication_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<sca_authentication_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</sca_authentication_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK Created
{
"transaction": {
"on_test_gateway": false,
"created_at": "2020-11-12T15:28:15Z",
"updated_at": "2020-11-12T15:28:16Z",
"succeeded": false,
"state": "pending",
"token": "VvplgnvtAWAoa38801a7e24qAHI",
"transaction_type": "Authorize",
"order_id": null,
"ip": "127.0.0.1",
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": null,
"gateway_latency_ms": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"sub_merchant_key": null,
"warning": null,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"smart_routed": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
},
{
"failover_transaction": [
]
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2020-11-10T19:38:14Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
},
"sca_authentication": {
"created_at": "2020-11-12T15:28:15Z",
"updated_at": "2020-11-12T15:28:16Z",
"succeeded": true,
"state": "succeeded",
"token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"flow_performed": "challenge",
"message": null,
"sca_provider_key": "6JXUReoA9KgnYoSchcJU0OAA6N0",
"three_ds_version": "2.2.0",
"ecommerce_indicator": null,
"authentication_value": null,
"directory_server_transaction_id": "5c06e665-3675-494e-9ccf-cc078ebd8dc9",
"authentication_value_algorithm": null,
"directory_response_status": "C",
"authentication_response_status": "C",
"required_action": "challenge",
"acs_reference_number": null,
"acs_rendering_type": null,
"acs_signed_content": null,
"acs_transaction_id": null,
"sdk_transaction_id": null,
"challenge_form": "<form action=\"https://testds3.seglan.com/server/authentication/load\" method=\"POST\">\n <input name=\"browserChallengeToken\" value=\"b3055a53-7c4d-4f71-bb33-742af0daa96f\" type=\"hidden\"/>\n</form>",
"challenge_form_embed_url": null,
"three_ds_server_trans_id": "b3055a53-7c4d-4f71-bb33-742af0daa96f",
"xid": null,
"enrolled": null,
"transaction_type": "Sca::Authentication"
}
}
}
<transaction>
<on_test_gateway type="boolean">false</on_test_gateway>
<created_at type="dateTime">2020-11-12T15:10:37Z</created_at>
<updated_at type="dateTime">2020-11-12T15:10:38Z</updated_at>
<succeeded type="boolean">false</succeeded>
<state>pending</state>
<token>X3WSJdOofHm4tJL84l3ZW8dtDal</token>
<transaction_type>Authorize</transaction_type>
<order_id nil="true"></order_id>
<ip>127.0.0.1</ip>
<description nil="true"></description>
<email nil="true"></email>
<sub_merchant_key nil="true"></sub_merchant_key>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id nil="true"></gateway_transaction_id>
<gateway_latency_ms nil="true"></gateway_latency_ms>
<stored_credential_initiator nil="true"></stored_credential_initiator>
<stored_credential_reason_type nil="true"></stored_credential_reason_type>
<warning nil="true"></warning>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<smart_routed type="boolean">false</smart_routed>
<message key="messages.transaction_pending">Pending</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2020-11-10T19:38:14Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<sca_authentication>
<created_at type="dateTime">2020-11-12T15:10:37Z</created_at>
<updated_at type="dateTime">2020-11-12T15:10:38Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>56wyNnSmuA6CWYP7w0MiYCVIbW6</token>
<flow_performed>challenge</flow_performed>
<message nil="true"></message>
<sca_provider_key>6JXUReoA9KgnYoSchcJU0OAA6N0</sca_provider_key>
<three_ds_version>2.2.0</three_ds_version>
<ecommerce_indicator nil="true"></ecommerce_indicator>
<authentication_value nil="true"></authentication_value>
<directory_server_transaction_id>b307301e-5ddc-476e-b4da-586327cfe9e9</directory_server_transaction_id>
<authentication_value_algorithm nil="true"></authentication_value_algorithm>
<directory_response_status>C</directory_response_status>
<authentication_response_status>C</authentication_response_status>
<required_action>challenge</required_action>
<acs_reference_number nil="true"></acs_reference_number>
<acs_rendering_type nil="true"></acs_rendering_type>
<acs_signed_content nil="true"></acs_signed_content>
<acs_transaction_id nil="true"></acs_transaction_id>
<sdk_transaction_id nil="true"></sdk_transaction_id>
<challenge_form><form action="https://testds3.seglan.com/server/authentication/load" method="POST">
<input name="browserChallengeToken" value="116e1940-c712-4b78-9f2c-0a6f976184d7" type="hidden"/>
</form></challenge_form>
<challenge_form_embed_url nil="true"></challenge_form_embed_url>
<three_ds_server_trans_id>116e1940-c712-4b78-9f2c-0a6f976184d7</three_ds_server_trans_id>
<xid nil="true"></xid>
<enrolled nil="true"></enrolled>
<transaction_type>Sca::Authentication</transaction_type>
</sca_authentication>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Authorize an SCA Authenticated payment method (already stored in the Spreedly environment) to be charged a specific amount.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ sca_authentication_token required |
The token received in response body of SCA Authenticate endpoint when performing an SCA Authentication on a specified payment method. See instructions to obtain |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
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.
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in credit card
POST /v1/gateways/<gateway_token>/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"credit_card": {
"first_name": "Joe",
"last_name": "Smith",
"number": "4111111111111111",
"verification_value": "123",
"month": "12",
"year": "2029"
},
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<credit_card>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<number>4111111111111111</number>
<verification_value>423</verification_value>
<month>3</month>
<year>2029</year>
</credit_card>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:05:06Z",
"updated_at": "2018-11-07T15:05:06Z",
"succeeded": true,
"state": "succeeded",
"token": "QE9CjpENGdSS5jgLfE6kG48Zaer",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "63",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful authorize",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:05:06Z",
"updated_at": "2018-11-07T15:05:06Z"
},
"shipping_address": {
"name": "Joe Smith",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "2c3c0YYECuX7e111VzhFg2AX6ZS",
"created_at": "2018-11-07T15:05:06Z",
"updated_at": "2018-11-07T15:05:06Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Smith",
"month": 12,
"year": 2018,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Joe Smith",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:05:06Z</created_at>
<updated_at type="dateTime">2018-11-07T15:05:06Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>FFtwzoTAVL34J30Ec8RscozhHWr</token>
<transaction_type>Authorization</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>65</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Joey Jones</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful authorize</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-11-07T15:05:06Z</created_at>
<updated_at type="dateTime">2018-11-07T15:05:06Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>BtcR0qpBzqqlwDF4KT6oZukwA8z</token>
<created_at type="dateTime">2018-11-07T15:05:06Z</created_at>
<updated_at type="dateTime">2018-11-07T15:05:06Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<month type="integer">3</month>
<year type="integer">2020</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Joey Jones</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ credit_card | Credit card element |
| ❯❯ first_name required |
The first name of the cardholder |
| ❯❯ last_name required |
The last name of the cardholder |
| ❯❯ number required |
The full card number |
| ❯❯ verification_value | The verification value (CVV/CVC) of the card |
| ❯❯ month required |
The expiration month of the card |
| ❯❯ year required |
The expiration year of the card |
| ❯❯ full_name optional: either full_name or both first_name and last_name are required |
The full name of the cardholder. If provided, will be parsed to determine first_name and last_name. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ gateway_specific_fields | Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_provider_key | SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
| ❯ ignore_failed_authentication_result | Complete 3DS2 Global transaction when authentication fails. |
| ❯ allow_blank_name | true if this payment method should skip the name validation requirement |
| ❯ allow_expired_date | true if this payment method should skip the expired date validation requirement |
| ❯ allow_blank_date | true if this payment method should skip the expiration date validation requirement |
allow_blank_date, allow_expired_date and allow_blank_name are not sticky flags meaning that they have to be passed
in every time a payment method is created or update.
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in Apple Pay
POST /v1/gateways/<gateway_token>/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"apple_pay": {
"payment_data": {
"version": "EC_v1",
"data": "QlzLxRFnNP9/GTaMhBwgmZ2ywntbr9iOcBY4TjPZyNrnCwsJd2cq61bDQjo3agVU0LuEot2VIHHocVrp5jdy0FkxdFhGd+j7hPvutFYGwZPcuuBgROb0beA1wfGDi09I+OWL+8x5+8QPl+y8EAGJdWHXr4CuL7hEj4CjtUhfj5GYLMceUcvwgGaWY7WzqnEO9UwUowlDP9C3cD21cW8osn/IKROTInGcZB0mzM5bVHM73NSFiFepNL6rQtomp034C+p9mikB4nc+vR49oVop0Pf+uO7YVq7cIWrrpgMG7ussnc3u4bmr3JhCNtKZzRQ2MqTxKv/CfDq099JQIvTj8hbqswv1t+yQ5ZhJ3m4bcPwrcyIVej5J241R7dNPu9xVjM6LSOX9KeGZQGud",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTUwMjI0MTgzNTU5WjAvBgkqhkiG9w0BCQQxIgQgohbm8d0A42OAyMnc5fsgQoCNYjtEd/W/dW6+yezIwoAwCgYIKoZIzj0EAwIERzBFAiEAtEkap+JHypwfL1EdabD7RWPZol3na0LhMk9XzLhis0oCIGwxzOhQnMw+Td8WglTMNYcidqeYILTGzn3zMEXmW3j7AAAAAAAA",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQwjaSlnZ3EXpwKfWAd2e1VnbS6vmioMyF6bNcq/Qd65NLQsjrPatzHWbJzG7v5vJtAyrf6WhoNx3C1VchQxYuw==",
"transactionId": "e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371",
"publicKeyHash": "/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI="
}
},
"test_card_number": "4111111111111111"
}
}
}
<transaction>
<apple_pay>
<payment_data>
<![CDATA[{"version":"EC_v1","data":"QlzLxRFnNP9/GTaMhBwgmZ2ywntbr9iOcBY4TjPZyNrnCwsJd2cq61bDQjo3agVU0LuEot2VIHHocVrp5jdy0FkxdFhGd+j7hPvutFYGwZPcuuBgROb0beA1wfGDi09I+OWL+8x5+8QPl+y8EAGJdWHXr4CuL7hEj4CjtUhfj5GYLMceUcvwgGaWY7WzqnEO9UwUowlDP9C3cD21cW8osn/IKROTInGcZB0mzM5bVHM73NSFiFepNL6rQtomp034C+p9mikB4nc+vR49oVop0Pf+uO7YVq7cIWrrpgMG7ussnc3u4bmr3JhCNtKZzRQ2MqTxKv/CfDq099JQIvTj8hbqswv1t+yQ5ZhJ3m4bcPwrcyIVej5J241R7dNPu9xVjM6LSOX9KeGZQGud","signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTUwMjI0MTgzNTU5WjAvBgkqhkiG9w0BCQQxIgQgohbm8d0A42OAyMnc5fsgQoCNYjtEd/W/dW6+yezIwoAwCgYIKoZIzj0EAwIERzBFAiEAtEkap+JHypwfL1EdabD7RWPZol3na0LhMk9XzLhis0oCIGwxzOhQnMw+Td8WglTMNYcidqeYILTGzn3zMEXmW3j7AAAAAAAA","header":{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQwjaSlnZ3EXpwKfWAd2e1VnbS6vmioMyF6bNcq/Qd65NLQsjrPatzHWbJzG7v5vJtAyrf6WhoNx3C1VchQxYuw==","transactionId":"e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371","publicKeyHash":"/4UKqrtx7AmlRvLatYt9LDt64IYo+G9eaqqS6LFOAdI="}}
]]>
</payment_data>
<test_card_number>4111111111111111</test_card_number>
</apple_pay>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T15:31:55Z",
"updated_at": "2017-11-21T15:31:55Z",
"succeeded": true,
"state": "succeeded",
"token": "6WH4NTBViQ1ZSr2jehjT8mmW0tY",
"transaction_type": "Authorization",
"order_id": "e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371",
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "60",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful authorize",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T15:31:55Z",
"updated_at": "2017-11-21T15:31:55Z"
},
"shipping_address": {
"name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "FNvcFYxvAaCpDRJEd12UOci6cBz",
"created_at": "2017-11-21T15:31:55Z",
"updated_at": "2017-11-21T15:31:55Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": null,
"last_name": null,
"month": 3,
"year": 2018,
"full_name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "apple_pay",
"errors": [
]
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T15:31:56Z</created_at>
<updated_at type="dateTime">2017-11-21T15:31:56Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>2y7JDkH3py6T1N7dgAlrifLjwh2</token>
<transaction_type>Authorization</transaction_type>
<order_id>e220cc1504ec15835a375e9e8659e27dcbc1abe1f959a179d8308dd8211c9371</order_id>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>63</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name></name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful authorize</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2017-11-21T15:31:56Z</created_at>
<updated_at type="dateTime">2017-11-21T15:31:56Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>3HzuJfWQWphcXdEkO98tRInhwcS</token>
<created_at type="dateTime">2017-11-21T15:31:56Z</created_at>
<updated_at type="dateTime">2017-11-21T15:31:56Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name nil="true"/>
<last_name nil="true"/>
<month type="integer">3</month>
<year type="integer">2018</year>
<full_name></full_name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>apple_pay</payment_method_type>
<errors>
</errors>
</payment_method>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ apple_pay | Apple pay element |
| ❯❯ payment_data required |
The JSON serialized paymentData property of an Apple Pay PKPaymentToken |
| ❯❯ test_card_number | Apple Pay does not provide a way to create a test payment token. To mark this as a test Apple Pay payment method, specify a test card number in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Apple Pay payment data. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Pass-in Google Pay
POST /v1/gateways/<gateway_token>/authorize.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"amount": 1122,
"currency_code": "USD",
"google_pay": {
"payment_data": {
"signature": "MEUCIA6SGVRwhOyeYRkeDUUNwB/kGtyfQAlOsg7NZydT17u/AiEA48BhWGQEF1EbEU0J+m8eSK3rTfhok9QqpiFVbME+Ky0=",
"protocolVersion": "ECv1",
"signedMessage": "{\"encryptedMessage\":\"3v4IcT/eovIDP2WF8iRUy4qWQnE9Cx0vQxIZ5f9i3Emv3Tzs1AzvB7cxXhxrjp9FVIzdOwsZAPAsm03gvoYq8Xdr70XvrVRd2MFwQhMC7IV/uEsthw4JsR8oCkbI5v/zqhu2B+JodFgavNliHcpKBgijy2D6bpx7jXEkM39M/L4oBObFxFrhVSLA1GjOV6A5gLAXNXt0ffkCYekihqAyJrWlk3sCBDCF5SUiAKEIOIZtzZLgusxjVp6ufZHOHm/53uhAi6JWSJ1E6G5aaYGtULYdwgURHtxN5OIzQPYlEGctaQd5tgfCsBFfGkYyN1GRNgclbaLzAfk/Jn7/6IVKuV0ol3xubTcnjGTZXwtTjiEyYDoz1yVqB9ViMmJa55L6nBtbbAkcNEgAi7dPnrbvBGEP7QWsNT9D71g8SWrlRTCYUAOyuamaQhofG4ul1IVjmltdAy2BHBWpqgJnR9kczydQyE7uDiqhSC1/0eG8GCGIqoi8XfOioGXfMyLZ1p2ZcNK9ECjzUrH/edrwgtShxgWuWMwQTM4DQlVTAA/R4DVs192YWZcc7jm5wLqZ0+XEaPuighJM1Ps1Egeccg\\u003d\\u003d\",\"ephemeralPublicKey\":\"BA2SvF9BdCX7Tl1wwRkyLzTfqhctobhZgSugC9Cz77XNUCBOBMfFyJQt506PUs89D6IJZZfOkZopy0shRF9Uph4\\u003d\",\"tag\":\"Uhin1BE7KAuuiam7eEQFimRUDd9Xn6tZc2fClTpfrXQ\\u003d\"}"
},
"test_card_number": "4111111111111111"
}
}
}
<transaction>
<amount>1122</amount>
<currency_code>USD</currency_code>
<google_pay>
<payment_data>
<![CDATA[{"signature":"MEUCIA6SGVRwhOyeYRkeDUUNwB/kGtyfQAlOsg7NZydT17u/AiEA48BhWGQEF1EbEU0J+m8eSK3rTfhok9QqpiFVbME+Ky0\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"3v4IcT/eovIDP2WF8iRUy4qWQnE9Cx0vQxIZ5f9i3Emv3Tzs1AzvB7cxXhxrjp9FVIzdOwsZAPAsm03gvoYq8Xdr70XvrVRd2MFwQhMC7IV/uEsthw4JsR8oCkbI5v/zqhu2B+JodFgavNliHcpKBgijy2D6bpx7jXEkM39M/L4oBObFxFrhVSLA1GjOV6A5gLAXNXt0ffkCYekihqAyJrWlk3sCBDCF5SUiAKEIOIZtzZLgusxjVp6ufZHOHm/53uhAi6JWSJ1E6G5aaYGtULYdwgURHtxN5OIzQPYlEGctaQd5tgfCsBFfGkYyN1GRNgclbaLzAfk/Jn7/6IVKuV0ol3xubTcnjGTZXwtTjiEyYDoz1yVqB9ViMmJa55L6nBtbbAkcNEgAi7dPnrbvBGEP7QWsNT9D71g8SWrlRTCYUAOyuamaQhofG4ul1IVjmltdAy2BHBWpqgJnR9kczydQyE7uDiqhSC1/0eG8GCGIqoi8XfOioGXfMyLZ1p2ZcNK9ECjzUrH/edrwgtShxgWuWMwQTM4DQlVTAA/R4DVs192YWZcc7jm5wLqZ0+XEaPuighJM1Ps1Egeccg\\u003d\\u003d\",\"ephemeralPublicKey\":\"BA2SvF9BdCX7Tl1wwRkyLzTfqhctobhZgSugC9Cz77XNUCBOBMfFyJQt506PUs89D6IJZZfOkZopy0shRF9Uph4\\u003d\",\"tag\":\"Uhin1BE7KAuuiam7eEQFimRUDd9Xn6tZc2fClTpfrXQ\\u003d\"}"}
]]>
</payment_data>
<test_card_number>4111111111111111</test_card_number>
</google_pay>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-09-25T15:59:50Z",
"updated_at": "2018-09-25T15:59:50Z",
"succeeded": true,
"state": "succeeded",
"token": "KnO3nYY9j10N1ajoELgexsNZAna",
"transaction_type": "Authorization",
"order_id": "AH2EjtcuYvaTXHijJ9TKSJXyBjs-NltywbAVH_-oVmjtctSwWsuU1xWUTqrsamtLM-xs8-c0wQY7t6jd5MmJfMxWca_WKjXIjk6vXr8Zcn-NCftMQwQLN2KmF1_LhgBo_Nm_FXo1plC-",
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "59",
"gateway_latency_ms": 0,
"amount": 1122,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "IRMVoS9jurugLBkX8pM7YTmTj9F",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful authorize",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-09-25T15:59:50Z",
"updated_at": "2018-09-25T15:59:50Z"
},
"shipping_address": {
"name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "2ZYC0goUFpoLp3hEnlS7yrj4LFu",
"created_at": "2018-09-25T15:59:50Z",
"updated_at": "2018-09-25T15:59:50Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": true,
"metadata": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": null,
"last_name": null,
"month": 12,
"year": 2023,
"full_name": "",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "google_pay",
"google_pay_type": "TOKENIZED_CARD",
"errors": [
]
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-09-25T15:59:50Z</created_at>
<updated_at type="dateTime">2018-09-25T15:59:50Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>2ui6gpynOQyKfaBLMxh3kEhKyN5</token>
<transaction_type>Authorization</transaction_type>
<order_id>AH2EjtcuYvaTXHijJ9TKSJXyBjs-NltywbAVH_-oVmjtctSwWsuU1xWUTqrsamtLM-xs8-c0wQY7t6jd5MmJfMxWca_WKjXIjk6vXr8Zcn-NCftMQwQLN2KmF1_LhgBo_Nm_FXo1plC-</order_id>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>62</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">1122</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">true</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>IRMVoS9jurugLBkX8pM7YTmTj9F</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name></name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful authorize</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-09-25T15:59:50Z</created_at>
<updated_at type="dateTime">2018-09-25T15:59:50Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>2izOJqSOfy7HZesSmdQYfmAKTQw</token>
<created_at type="dateTime">2018-09-25T15:59:50Z</created_at>
<updated_at type="dateTime">2018-09-25T15:59:50Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name nil="true"/>
<last_name nil="true"/>
<month type="integer">12</month>
<year type="integer">2023</year>
<full_name></full_name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>google_pay</payment_method_type>
<google_pay_type>TOKENIZED_CARD</google_pay_type>
<errors>
</errors>
</payment_method>
</transaction>
Pass a Google Pay payment method directly into the authorize request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ google_pay | Google Pay element |
| ❯❯ payment_data required |
The JSON-formatted encrypted payload Google Pay Payment Token |
| ❯❯ test_card_number | Specify a test card number in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Google Pay payment data. |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ retain_on_success | If the card is verified, retain it so it can be used for future transactions |
| ❯ ip | The IP address of the end-user customer. If one is not provided, this will default to 127.0.0.1. To actually send a nil value, this parameter must be set to "omit". |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ stored_credential_initiator | Who is initiating this request, merchant or cardholder |
| ❯ stored_credential_reason_type | What kind of transaction is the payment method being used for. e.g. recurring, unscheduled, or installment |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ callback_url optional |
The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by callback_format if provided or XML if callback_format is not present or null. (default: null) |
| ❯ callback_format optional |
The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified callback_url. If provided, the value must be one of json or xml. (default: xml) |
| ❯ shipping_address | Override the customer shipping address associated with the payment method for this transaction |
| ❯❯ name | Customer’s name in the shipping address |
| ❯❯ address1 | Customer’s shipping address, line 1 |
| ❯❯ address2 | Customer’s shipping address, line 2 |
| ❯❯ city | Customer’s shipping city |
| ❯❯ state | Customer’s shipping state/province |
| ❯❯ zip | Customer’s shipping zip |
| ❯❯ country | Customer’s shipping country |
| ❯❯ phone_number | Customer’s shipping phone |
| ❯ billing_address | Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method. |
| ❯❯ name | Customer’s name in the billing address |
| ❯❯ address1 | Customer’s billing address, line 1 |
| ❯❯ address2 | Customer’s billing address, line 2 |
| ❯❯ city | Customer’s billing city |
| ❯❯ state | Customer’s billing state/province |
| ❯❯ zip | Customer’s billing zip |
| ❯❯ country | Customer’s billing country |
| ❯❯ phone_number | Customer’s billing phone |
| ❯ transaction_metadata optional |
Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
| ❯ sca_authentication | The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the SCA Authentication Show details for more information on this object. |
Capture
Full amount
POST /v1/transactions/<transaction_token>/capture.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T18:51:26Z",
"updated_at": "2017-11-21T18:51:26Z",
"succeeded": true,
"state": "succeeded",
"token": "UAooev0WJDbSyuh0CqwHGi8WDML",
"transaction_type": "Capture",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
},
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "65",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful capture",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T18:51:26Z",
"updated_at": "2017-11-21T18:51:26Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"reference_token": "HayOiJhe9tZZb2xOIis4j3I92Ic"
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T18:51:27Z</created_at>
<updated_at type="dateTime">2017-11-21T18:51:27Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>AcmX05msHV6QtkqHufm2IvnUQDw</token>
<transaction_type>Capture</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>50</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name nil="true"></name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful capture</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2017-11-21T18:51:27Z</created_at>
<updated_at type="dateTime">2017-11-21T18:51:27Z</updated_at>
</response>
<api_urls>
</api_urls>
<reference_token>2E61br6muiAImfGVsKyIWiesgiT</reference_token>
</transaction>
Capture all funds previously reserved via an authorize.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying the original authorize transaction |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions. |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause. |
Partial amount
POST /v1/transactions/<transaction_token>/capture.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"amount": 50,
"currency_code": "USD"
}
}
<transaction>
<amount>50</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T18:51:28Z",
"updated_at": "2017-11-21T18:51:28Z",
"succeeded": true,
"state": "succeeded",
"token": "S3VrIobz0gC0AI771ml1CndOLs5",
"transaction_type": "Capture",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "47",
"gateway_latency_ms": 0,
"amount": 50,
"currency_code": "USD",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful capture",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T18:51:28Z",
"updated_at": "2017-11-21T18:51:28Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"reference_token": "XN4DwAxZRC6tE7LfuKxKGBTetjJ"
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T18:51:29Z</created_at>
<updated_at type="dateTime">2017-11-21T18:51:29Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>J7fUGpBN7s0C0R2dXHW4ridM1TE</token>
<transaction_type>Capture</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>44</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">50</amount>
<currency_code>USD</currency_code>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name nil="true"></name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful capture</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2017-11-21T18:51:29Z</created_at>
<updated_at type="dateTime">2017-11-21T18:51:29Z</updated_at>
</response>
<api_urls>
</api_urls>
<reference_token>KrK450UpFJuRB0ZrTDRsHomXkuy</reference_token>
</transaction>
Capture a partial amount from an authorize by specifying an amount.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying the original authorize transaction |
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| transaction | Root element |
| ❯ amount | The amount to capture, as an integer. E.g., 1000 for $10.00. If not provided, the full amount of the original authorize will be captured. |
| ❯ currency_code | The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions. |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause. |
Void
POST /v1/transactions/<transaction_token>/void.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T18:51:34Z",
"updated_at": "2017-11-21T18:51:34Z",
"succeeded": true,
"state": "succeeded",
"token": "9IstHnD1haMTBWkIjlYWb5TwuO0",
"transaction_type": "Void",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
},
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "61",
"gateway_latency_ms": 0,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful void",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T18:51:34Z",
"updated_at": "2017-11-21T18:51:34Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"reference_token": "FVTLuCm5KfHD8fyZpP8GwjTH71I"
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T18:51:35Z</created_at>
<updated_at type="dateTime">2017-11-21T18:51:35Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>25MTT3u0QeXxlV5ZkXXKzU7983k</token>
<transaction_type>Void</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>51</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name nil="true"></name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful void</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2017-11-21T18:51:35Z</created_at>
<updated_at type="dateTime">2017-11-21T18:51:35Z</updated_at>
</response>
<reference_token>JYHEX7pkuKqWfZ6SjDrtIp8ZPeJ</reference_token>
</transaction>
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.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying the original authorize or purchase transaction |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions. |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause. |
Credit (refund)
Full amount
POST /v1/transactions/<transaction_token>/credit.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-11-21T15:17:42Z",
"updated_at": "2017-11-21T15:17:42Z",
"succeeded": true,
"state": "succeeded",
"token": "TBuWJz3OyvaDgcHyEhmY1hv9InB",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
},
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "54",
"gateway_latency_ms": 0,
"amount": 100,
"currency_code": "USD",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "Zi0OHhR0fn1dSGym1Wol302ajDY",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful credit",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-11-21T15:17:42Z",
"updated_at": "2017-11-21T15:17:42Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
],
"reference_token": "BE3lL76bUzUSIbFF4w7VBJtvxCW"
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-11-21T15:17:43Z</created_at>
<updated_at type="dateTime">2017-11-21T15:17:43Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>KZULrJmH9mOYoSd0pAEwFloJuTz</token>
<transaction_type>Credit</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>50</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>Zi0OHhR0fn1dSGym1Wol302ajDY</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name nil="true"></name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful credit</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2017-11-21T15:17:43Z</created_at>
<updated_at type="dateTime">2017-11-21T15:17:43Z</updated_at>
</response>
<api_urls>
</api_urls>
<reference_token>BY60fOSH6gPIKXTrkXPiuNwaonA</reference_token>
</transaction>
Refund the full amount of a purchase or capture.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying the original purchase or capture transaction |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions. |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause. |
Partial amount
POST /v1/transactions/<transaction_token>/credit.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"amount": 50,
"currency_code": "USD"
}
}
<transaction>
<amount>50</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-07-27T17:54:31Z",
"updated_at": "2017-07-27T17:54:31Z",
"succeeded": true,
"state": "succeeded",
"token": "RpJnRjeZFxJyUVLmFJ7hQAqKntx",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "57",
"gateway_latency_ms": 0,
"amount": 50,
"currency_code": "USD",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"response": {
"success": true,
"message": "Successful credit",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-07-27T17:54:31Z",
"updated_at": "2017-07-27T17:54:31Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
],
"reference_token": "8LpIau42ocEyNrwIMUYjHxvZTd2"
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-07-27T17:54:32Z</created_at>
<updated_at type="dateTime">2017-07-27T17:54:32Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>ENtCseMTaFKjIn8cRQUhE6K6CRm</token>
<transaction_type>Credit</transaction_type>
<order_id nil="true"></order_id>
<ip nil="true"></ip>
<description nil="true"></description>
<email nil="true"></email>
<merchant_name_descriptor nil="true"></merchant_name_descriptor>
<merchant_location_descriptor nil="true"></merchant_location_descriptor>
<gateway_specific_fields nil="true"></gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>53</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">50</amount>
<currency_code>USD</currency_code>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<shipping_address>
<name nil="true"></name>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful credit</message>
<avs_code nil="true"></avs_code>
<avs_message nil="true"></avs_message>
<cvv_code nil="true"></cvv_code>
<cvv_message nil="true"></cvv_message>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"></error_detail>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"></fraud_review>
<created_at type="dateTime">2017-07-27T17:54:32Z</created_at>
<updated_at type="dateTime">2017-07-27T17:54:32Z</updated_at>
</response>
<api_urls>
</api_urls>
<reference_token>XFMqXNAcsXtBCzO7RpcnXQOWWFD</reference_token>
</transaction>
Refund a partial amount of a purchase by specifying an amount.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying the original purchase transaction |
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| transaction | Root element |
| ❯ amount | The amount to refund, as an integer. E.g., 1000 for $10.00. If not provided, the full amount of the original purchase will be refunded. |
| ❯ currency_code | The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions. |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause. |
General credit
POST /v1/gateways/<gateway_token>/general_credit.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2021-03-09T16:23:27Z",
"updated_at": "2021-03-09T16:23:27Z",
"succeeded": true,
"state": "succeeded",
"token": "Wiio36yh5SdF1kdxznSdQIO9SCM",
"transaction_type": "GeneralCredit",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "65",
"gateway_latency_ms": 0,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"warning": null,
"application_id": null,
"amount": 100,
"currency_code": "USD",
"payment_method_added": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful general_credit",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2021-03-09T16:23:27Z",
"updated_at": "2021-03-09T16:23:27Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
],
"attempt_3dsecure": false,
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2021-03-09T16:23:27Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value"
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2021-03-09T16:23:27Z</created_at>
<updated_at type="dateTime">2021-03-09T16:23:27Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>JPD7BDA0MDVix2bYKN5N9b9Wy26</token>
<transaction_type>GeneralCredit</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<sub_merchant_key nil="true"/>
<description nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>59</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<warning nil="true"/>
<application_id nil="true"/>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful general_credit</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2021-03-09T16:23:27Z</created_at>
<updated_at type="dateTime">2021-03-09T16:23:27Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2021-03-08T20:01:08Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"/>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
Add funds to a credit card outside the scope of a previous reference transaction. This is different from credit which refunds money only up to the amount that had been taken during a previous transaction.
Support for this general credit depends on the gateway.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ amount required |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ currency_code required |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ order_id | The merchant specified order id. If not provided, the Spreedly transaction token will be used. |
| ❯ description | A human readable description of the transaction which will be passed to the gateway if it’s supported |
| ❯ continue_caching | A boolean option to keep the cvv cached for a few minutes. Otherwise cvv is deleted immediately. |
| ❯ ip | The IP address of the end-user customer |
| Override the customer email address associated with the payment method for this transaction | |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
Verify
POST /v1/gateways/<gateway_token>/verify.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"retain_on_success": true
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<retain_on_success>true</retain_on_success>
</transaction>
HTTPS/1.1 200 OK
{
"transaction": {
"on_test_gateway": true,
"created_at": "2018-11-07T15:10:26Z",
"updated_at": "2018-11-07T15:10:26Z",
"succeeded": true,
"state": "succeeded",
"token": "7H6kWRX0jxtaniT4em8ZfRMfcjR",
"transaction_type": "Verification",
"order_id": null,
"ip": null,
"sub_merchant_key": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "59",
"gateway_latency_ms": 20,
"currency_code": null,
"retain_on_success": true,
"payment_method_added": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"gateway_type": "test",
"response": {
"success": true,
"message": "Successful verify",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2018-11-07T15:10:26Z",
"updated_at": "2018-11-07T15:10:26Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2018-11-07T15:10:26Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2018-11-07T15:10:25Z</created_at>
<updated_at type="dateTime">2018-11-07T15:10:26Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>8I9G697eo64d3hOvix8wdgaj3ml</token>
<transaction_type>Verification</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<sub_merchant_key nil="true">
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>44</gateway_transaction_id>
<gateway_latency_ms type="integer">24</gateway_latency_ms>
<currency_code nil="true"/>
<retain_on_success type="boolean">true</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful verify</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2018-11-07T15:10:26Z</created_at>
<updated_at type="dateTime">2018-11-07T15:10:26Z</updated_at>
</response>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2018-11-07T15:10:01Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>string value</key>
<another_key type="integer">123</another_key>
<final_key type="boolean">true</final_key>
</metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
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.
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.
URL Parameters
| Parameter | Description |
|---|---|
| gateway_token required |
The token of the gateway to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to verify |
| ❯ retain_on_success optional |
If the card is verified, retain it so it can be used for future transactions |
| ❯ currency_code optional |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ ip optional |
If the gateway requires an allowed IP address |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
| ❯ sca_authentication_token optional |
The token received in response body of SCA Authenticate endpoint when performing an SCA Authentication on a specified payment method. See instructions to obtain |
| ❯ sca_provider_key optional |
SCA Provider token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our Spreedly 3DS2 Global Guide for more info. |
| ❯ sca_authentication_parameters optional |
Additional fields that are accepted by the Sca Authentication, including a test_scenario object to indicate valid 3DS2 test flow options and an exemption_type field to request an exemption. Please refer to our 3DS2 Global Guide to learn more. |
| ❯ gateway_specific_fields optional |
Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under gateway_specific_fields and under the gateway’s name, i.e. gateway_type. Please refer to using a payment method for more info. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction(s) | Root element |
| ❯ token | The token uniquely identifying this transaction at Spreedly |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ gateway_transaction_id | The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions |
| ❯ retain_on_success | If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the payment_method/storage_state field |
| ❯ payment_method_added | If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method |
| ❯ response | Unmodified details of the gateway response, including the message and error_code, if applicable. For failed transactions these fields can help determine the root cause |
| ❯ payment_method | The payment method used in this transaction |
| ❯ merchant_profile_key | The token of the Merchant Profile associated with the gateway used for the transaction |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ gateway_specific_response_fields | A hash containing unique optional fields that a gateway may return based on certain customized options. |
| ❯ transaction_metadata | The hash of key/value pairs that was included in the transaction request body. |
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Merchant Profiles
List
GET /v1/merchant_profiles.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"merchant_profiles": [
{
"token": "LsExVd1sJFsomL4zthCymHMj9hS",
"description": "updated Merchant description",
"created_at": "2020-11-09T18:48:01Z",
"updated_at": "2022-02-09T21:17:30Z",
"sub_merchant_key": null,
"card_networks": {
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"amex": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
}
}
},
{
"token": "SNXAM148zQHn4e6zM7L7lpVko65",
"description": null,
"created_at": "2021-05-25T19:11:43Z",
"updated_at": "2021-05-25T19:11:43Z",
"sub_merchant_key": null,
"card_networks": {
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"amex": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
}
}
}
]
}
<merchant_profiles>
<merchant_profile>
<card_networks>
<visa>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</visa>
<mastercard>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</mastercard>
<amex>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</amex>
</card_networks>
<token>LsExVd1sJFsomL4zthCymHMj9hS</token>
<description>updated Merchant description</description>
<created_at type="dateTime">2020-11-09T18:48:01Z</created_at>
<updated_at type="dateTime">2022-02-09T21:17:30Z</updated_at>
<sub_merchant_key nil="true"></sub_merchant_key>
</merchant_profile>
<merchant_profile>
<card_networks>
<visa>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</visa>
<mastercard>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</mastercard>
<amex>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</amex>
</card_networks>
<token>SNXAM148zQHn4e6zM7L7lpVko65</token>
<description nil="true"></description>
<created_at type="dateTime">2021-05-25T19:11:43Z</created_at>
<updated_at type="dateTime">2021-05-25T19:11:43Z</updated_at>
<sub_merchant_key nil="true"></sub_merchant_key>
</merchant_profile>
</merchant_profiles>
Retrieve an ordered and paginated list of all merchant profiles in the environment.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
| count | The number of merchant profiles to return. By default returns 20, maximum allowed is 100. |
Response body
Notable response elements include:
| Element | Description |
|---|---|
| merchant_profiles | Root Element |
| ❯ token | The token uniquely identifying this merchant profile at Spreedly |
| ❯ description | A custom description that the merchant can assign to characterize the merchant profile. |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the Merchant Profile if one exists. |
| ❯ card_networks | A nested object containing merchant info per card brand that are necessary to generate 3DS credentials per merchant. See acquirer_merchant_id, merchant_name, country_code, and mcc below for nested field information. |
| ❯❯ acquirer_merchant_id | The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯❯ merchant_name | Assigned by the acquiring bank; please contact them |
| ❯❯ country_code | Country Code in ISO 3166-1 numeric format. |
Create
POST /v1/merchant_profiles.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"merchant_profile": {
"description": "Spreedly",
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"merchant_name": "Spreedly",
"country_code": "840",
"mcc": "5978"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"merchant_name": "Spreedly",
"country_code": "840",
"mcc": "5978"
},
"amex": {
"acquirer_merchant_id": "spreedlys_mid",
"merchant_name": "Spreedly",
"country_code": "840",
"mcc": "5978"
},
"discover": {
"acquirer_merchant_id": "spreedlys_mid",
"merchant_name": "Spreedly",
"country_code": "840",
"mcc": "5978"
}
}
}
<merchant_profile>
<description>Spreedly</description>
<visa>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
<mcc>5978</mcc>
</visa>
<mastercard>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
<mcc>5978</mcc>
</mastercard>
<amex>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
<mcc>5978</mcc>
</amex>
<discover>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
<mcc>5978</mcc>
</discover>
</merchant_profile>
HTTPS/1.1 200 OK Created
{
"merchant_profile": {
"token": "LXeWiT9QNMPbLeZC7Z86ep4xh6s",
"description": "Spreedly",
"created_at": "2023-05-31T19:28:04Z",
"updated_at": "2023-05-31T19:28:04Z",
"sub_merchant_key": null,
"card_networks": {
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"amex": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"discover": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
}
}
}
}
<merchant_profile>
<card_networks>
<visa>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</visa>
<mastercard>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</mastercard>
<amex>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</amex>
<discover>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</discover>
</card_networks>
<token>6b3rjLugxUfuJGrZ9XteMHyROBk</token>
<description>Spreedly</description>
<created_at type="dateTime">2023-05-31T19:28:04Z</created_at>
<updated_at type="dateTime">2023-05-31T19:28:04Z</updated_at>
<sub_merchant_key nil="true"></sub_merchant_key>
</merchant_profile>
Create a Merchant Profile that holds the SCA Provider.
Request body
| Parameter | Description |
|---|---|
| merchant_profile | Root Element |
| ❯ description | A custom description that the merchant can assign to characterize the merchant profile. |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the Merchant Profile if one exists. |
| ❯ mastercard visa amex discover at least one required |
A nested object containing merchant info per card brand that are necessary to generate 3DS credentials per merchant. See acquirer_merchant_id, merchant_name, country_code, and mcc below for nested field information. |
| ❯❯ acquirer_merchant_id required |
The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ merchant_name required |
Assigned by the acquiring bank; please contact them |
| ❯❯ country_code required |
Country Code in ISO 3166-1 numeric format. |
| ❯❯ mcc required |
The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
Show
GET /v1/merchant_profiles/<merchant_profile_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"merchant_profile": {
"token": "6b3rjLugxUfuJGrZ9XteMHyROBk",
"description": "Spreedly",
"created_at": "2023-05-31T19:28:04Z",
"updated_at": "2023-05-31T19:28:04Z",
"sub_merchant_key": null,
"card_networks": {
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"amex": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"discover": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
}
}
}
}
<merchant_profile>
<card_networks>
<visa>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</visa>
<mastercard>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</mastercard>
<amex>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</amex>
<discover>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</discover>
</card_networks>
<token>6b3rjLugxUfuJGrZ9XteMHyROBk</token>
<description>Spreedly</description>
<created_at type="dateTime">2023-05-31T19:28:04Z</created_at>
<updated_at type="dateTime">2023-05-31T19:28:04Z</updated_at>
<sub_merchant_key nil="true"></sub_merchant_key>
</merchant_profile>
Get a merchant profile with the given token.
URL Parameters
| Parameter | Description |
|---|---|
| merchant_profile_token required |
The token of the merchant profile |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Parameter | Description |
|---|---|
| merchant_profile | Root Element |
| ❯ token | The token uniquely identifying this merchant profile at Spreedly |
| ❯ description | A custom description that the merchant can assign to characterize the merchant profile. |
| ❯ sub_merchant_key | The token of the Sub-merchant associated with the Merchant Profile if one exists. |
| ❯ card_networks | A nested object containing merchant info per card brand that are necessary to generate 3DS credentials per merchant. See acquirer_merchant_id, merchant_name, country_code, and mcc below for nested field information. |
| ❯❯ acquirer_merchant_id | The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯❯ merchant_name | Assigned by the acquiring bank; please contact them |
| ❯❯ country_code | Country Code in ISO 3166-1 numeric format. |
Update
PUT /v1/merchant_profiles/<merchant_profile_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"merchant_profile": {
"description": "updated Merchant description"
}
}
<merchant_profile>
<description>updated Merchant description</description>
</merchant_profile>
HTTPS/1.1 200 OK
{
"merchant_profile": {
"token": "6b3rjLugxUfuJGrZ9XteMHyROBk",
"description": "updated Merchant description",
"created_at": "2023-05-31T19:28:04Z",
"updated_at": "2023-08-24T16:29:18Z",
"sub_merchant_key": null,
"card_networks": {
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"amex": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
},
"discover": {
"acquirer_merchant_id": "spreedlys_mid",
"mcc": "5978",
"merchant_name": "Spreedly",
"country_code": "840"
}
}
}
}
<merchant_profile>
<card_networks>
<visa>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</visa>
<mastercard>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</mastercard>
<amex>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</amex>
<discover>
<acquirer_merchant_id>spreedlys_mid</acquirer_merchant_id>
<mcc>5978</mcc>
<merchant_name>Spreedly</merchant_name>
<country_code>840</country_code>
</discover>
</card_networks>
<token>6b3rjLugxUfuJGrZ9XteMHyROBk</token>
<description>updated Merchant description</description>
<created_at type="dateTime">2023-05-31T19:28:04Z</created_at>
<updated_at type="dateTime">2023-08-24T16:29:40Z</updated_at>
<sub_merchant_key nil="true"></sub_merchant_key>
</merchant_profile>
Update the description on the Merchant Profile. All other parameters of the Merchant Profile cannot be updated once created.
| Element | Description |
|---|---|
| merchant_profile | Root element |
| ❯ description | A custom description that the merchant can assign to characterize the merchant profile. |
SCA Providers
Create
POST /v1/sca/providers.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"sca_provider": {
"merchant_profile_key": "4pJUW6X81w6OtOLi0dI3W6DD9sY",
"type": "test",
"sandbox": true,
"mastercard": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"visa": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional",
"merchant_brand_id": "optional"
},
"amex": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"discover": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
}
}
}
<sca_provider>
<merchant_profile_key>4pJUW6X81w6OtOLi0dI3W6DD9sY</merchant_profile_key>
<type>spreedly</type>
<sandbox>true</sandbox>
<mastercard>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</mastercard>
<visa>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
<merchant_brand_id>optional</merchant_brand_id>
</visa>
<amex>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</amex>
<discover>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</discover>
</sca_provider>
HTTPS/1.1 200 OK Created
{
"sca_provider": {
"token": "6EskuBYV5DVyN7Mmy1pV41FqgbN",
"sandbox": true,
"mastercard": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"visa": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional",
"merchant_brand_id": "optional"
},
"amex": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"discover": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"created_at": "2023-06-06T18:02:26Z",
"updated_at": "2023-06-06T18:02:26Z",
"type": "test"
}
}
<sca_provider>
<token>ZKJUqtvImgwulsR4akwBNlJBNMk</token>
<sandbox type="boolean">true</sandbox>
<mastercard>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</mastercard>
<visa>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
<merchant_brand_id>optional</merchant_brand_id>
</visa>
<amex>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</amex>
<discover>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</discover>
<created_at type="dateTime">2023-06-06T18:02:25Z</created_at>
<updated_at type="dateTime">2023-06-06T18:02:26Z</updated_at>
<type>spreedly</type>
</sca_provider>
Create an SCA Provider on the given Merchant Profile. An SCA Provider can be used to run 3DS2 Global authentications on the authenticate endpoint or as part of authorize and purchase transactions.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request body
| Parameter | Description |
|---|---|
| sca_provider | Root Element |
| ❯ merchant_profile_key required |
The token returned upon creating a Merchant Profile |
| ❯ type required |
The type of SCA Provider being created. Currently only one type is supported: spreedly (case sensitive) |
| ❯ sandbox | If the SCA Provider account is to be provisioned in sandbox mode or not. false by default. |
| ❯ mastercard visa amex discover at least one required |
A nested object containing merchant info per card brand that is to be registered with the 3DS server. See acquirer_bin, merchant_url, and merchant_password below for nested field information. |
| ❯❯ acquirer_bin required |
The Acquirer Bank Identification Number (BIN) is identifying BIN for an acquiring bank. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ merchant_url required |
Fully qualified URL of the merchant’s main website or customer care site that contains a method of contact. |
| ❯❯ merchant_password | An old parameter for 3DS v1, unrelated to 3DS2. We support this parameter for those merchants who already have it activated and are migrating to our 3DSS, not for new ones. If you do not know the parameter, don’t take it into account. |
| ❯❯ merchant_brand_id | An optional parameter for an id issued to a merchant by a particular card scheme. When passed in the visa subhash it can be used to enable DAF via 3DS2 Global. |
Response Body
Notable response elements can be found in the table below.
| Element | Description |
|---|---|
| sca_provider | Root element |
| ❯ token | The token identifying your newly created SCA Provider. Can be used as the sca_provider_key url parameter on the authenticate endpoint or as the sca_provider_token field on authorize and purchase transactions. |
Show
GET /v1/sca/providers/ZI0HsrLtnvzvNry7f3HARhnOXbA.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"sca_provider": {
"token": "6EskuBYV5DVyN7Mmy1pV41FqgbN",
"sandbox": true,
"mastercard": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"visa": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional",
"merchant_brand_id": "optional"
},
"amex": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"discover": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"created_at": "2023-06-06T18:02:26Z",
"updated_at": "2023-06-06T18:02:26Z",
"type": "test"
}
}
<sca_provider>
<token>ZKJUqtvImgwulsR4akwBNlJBNMk</token>
<sandbox type="boolean">true</sandbox>
<mastercard>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</mastercard>
<visa>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
<merchant_brand_id>optional</merchant_brand_id>
</visa>
<amex>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</amex>
<discover>
<acquirer_bin>4444444444</acquirer_bin>
<merchant_url>https://spreedly.com</merchant_url>
<merchant_password>optional</merchant_password>
</discover>
<created_at type="dateTime">2023-06-06T18:02:25Z</created_at>
<updated_at type="dateTime">2023-06-06T18:02:26Z</updated_at>
<type>spreedly</type>
</sca_provider>
Get an SCA Provider with the given token. An SCA Provider can be used to run 3DS2 Global authentications on the authenticate endpoint or as part of authorize and purchase transactions.
URL Parameters
| Parameter | Description |
|---|---|
| sca_provider_token required |
The token of the SCA Provider |
| format required |
One of json or xml |
Response Body
| Parameter | Description |
|---|---|
| sca_provider | Root Element |
| ❯ token | The token identifying your newly created SCA Provider. Can be used as the sca_provider_key url parameter on the authenticate endpoint or as the sca_provider_token field on authorize and purchase transactions. |
| ❯ type required |
The type of SCA Provider being created. Currently only one type is supported: spreedly (case sensitive) |
| ❯ sandbox | If the SCA Provider account is to be provisioned in sandbox mode or not. false by default. |
| ❯ mastercard visa amex discover at least one required |
A nested object containing merchant info per card brand that is to be registered with the 3DS server. See acquirer_bin, merchant_url, and merchant_password below for nested field information. |
| ❯❯ acquirer_bin required |
The Acquirer Bank Identification Number (BIN) is identifying BIN for an acquiring bank. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ merchant_url required |
Fully qualified URL of the merchant’s main website or customer care site that contains a method of contact. |
| ❯❯ merchant_password | An old parameter for 3DS v1, unrelated to 3DS2. We support this parameter for those merchants who already have it activated and are migrating to our 3DSS, not for new ones. If you do not know the parameter, don’t take it into account. |
| ❯❯ merchant_brand_id | An optional parameter for an id issued to a merchant by a particular card scheme. When passed in the visa subhash it can be used to enable DAF via 3DS2 Global. |
SCA Authentications
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:
- SCA Authentication endpoint to perform an SCA Authentication on payment methods in order to be compliant with SCA enforcement.
- SCA Authentications can be performed as part of Spreedly Global 3DS transactions,
purchaseandauthorize
Show
GET /v1/transactions/.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"transaction": {
"created_at": "2022-03-07T19:04:52Z",
"updated_at": "2022-03-07T19:04:52Z",
"succeeded": true,
"state": "succeeded",
"token": "2YeYsQi9V41o6p3KDBdYnnWfFpU",
"flow_performed": "frictionless",
"message": "High confidence",
"sca_provider_key": "9oWxOAV4ZNSw8XDaSxFDohIHnet",
"amount": 100,
"currency_code": "EUR",
"ip": null,
"email": null,
"order_id": null,
"three_ds_version": "2.2.0",
"ecommerce_indicator": "05",
"authentication_value": "GPAitABmoHgFrVsJuqPMGLJbPQDc",
"directory_server_transaction_id": "8363c344-6db4-4126-a6a5-1f891b6b55c0",
"authentication_value_algorithm": null,
"directory_response_status": "Y",
"authentication_response_status": "Y",
"required_action": null,
"acs_reference_number": null,
"acs_rendering_type": null,
"acs_signed_content": null,
"acs_transaction_id": "b3683ce9-6f99-4f42-9836-61b28991f4ea",
"sdk_transaction_id": null,
"challenge_form": null,
"challenge_form_embed_url": null,
"three_ds_server_trans_id": "b3fd70e0-90a1-473a-ab80-e5c92dc46f2f",
"xid": null,
"enrolled": "true",
"transaction_type": "Sca::Authentication",
"gateway_transaction_key": null,
"callback_url": null,
"test_scenario": {
"scenario": "authenticated"
},
"three_ds_requestor_challenge_ind": null,
"trans_status_reason": "17"
}
}
<transaction>
<created_at type="dateTime">2022-03-07T19:04:51Z</created_at>
<updated_at type="dateTime">2022-03-07T19:04:51Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>EWjtM2APlFXWnTouki7BQTzE5N5</token>
<flow_performed>frictionless</flow_performed>
<message>High confidence</message>
<sca_provider_key>KCCsBgWfH1bZL098hG40YdzXJ3k</sca_provider_key>
<amount type="integer">100</amount>
<currency_code>EUR</currency_code>
<ip nil="true"></ip>
<email nil="true"></email>
<order_id nil="true"></order_id>
<three_ds_version>2.2.0</three_ds_version>
<ecommerce_indicator>05</ecommerce_indicator>
<authentication_value>lSTGSSknpTgsrTmeutRDpgltatGJ</authentication_value>
<directory_server_transaction_id>ca93ab75-4865-4e8d-a95c-8521ad90da8e</directory_server_transaction_id>
<authentication_value_algorithm nil="true"></authentication_value_algorithm>
<directory_response_status>Y</directory_response_status>
<authentication_response_status>Y</authentication_response_status>
<required_action nil="true"></required_action>
<acs_reference_number nil="true"></acs_reference_number>
<acs_rendering_type nil="true"></acs_rendering_type>
<acs_signed_content nil="true"></acs_signed_content>
<acs_transaction_id>101fd2b2-e5dc-4abd-9973-537bdc58f8c0</acs_transaction_id>
<sdk_transaction_id nil="true"></sdk_transaction_id>
<challenge_form nil="true"></challenge_form>
<challenge_form_embed_url nil="true"></challenge_form_embed_url>
<three_ds_server_trans_id>52c895a1-8c32-4a21-a16b-dfb2feeacb5c</three_ds_server_trans_id>
<xid nil="true"></xid>
<enrolled>true</enrolled>
<transaction_type>Sca::Authentication</transaction_type>
<gateway_transaction_key nil="true"></gateway_transaction_key>
<callback_url nil="true"></callback_url>
<test_scenario>
<scenario>authenticated</scenario>
</test_scenario>
<three_ds_requestor_challenge_ind nil="true"></three_ds_requestor_challenge_ind>
<trans_status_reason>17</trans_status_reason>
</transaction>
Get the transaction with the given token.
URL Parameters
| Parameter | Description |
|---|---|
| transaction_token required |
The token identifying this transaction at Spreedly |
| format required |
One of json or xml |
Response Body
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.
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying the transaction at Spreedly. This token can be passed into an authorize or purchase transaction via the sca_authentication_token field to automatically fill its payment_method_token and Third Party 3DS2 fields. |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ state | The current state of the authentication. Valid values are succeeded, failed, and pending |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ transaction_type | The type of transaction; contains “Sca::Authentication” for a Spreedly 3DS Global authentication |
| ❯ gateway_transaction_key | The Spreedly transaction token of the parent gateway transaction |
| ❯ sca_provider_key | The SCA Provider that was used to create the authentication |
| ❯ acs_transaction_id | The unique ID of the transaction given by the ACS server (3DS2 only) |
| ❯ three_ds_server_trans_id | The unique ID of the transaction given by the 3DS Server (3DS2 only) |
| ❯ directory_server_transaction_id | The unique ID of the transaction given by the directory server (3DS2 only) |
| ❯ xid | The transaction identifier given by the 3DS Server |
| ❯ three_ds_version | The version of 3DS that was used to authenticate the transaction |
| ❯ flow_performed | An enumerated field that denotes what flow was most recently performed. Valid values are frictionless, device_fingerprint, challenge, app_challenge, and not_authenticated. |
| ❯ ecommerce_indicator | Contains the ecommerce indicator (ECI) returned by the 3DS Server |
| ❯ directory_response_status | The transaction status given by the directory server in the initial response. This field’s value corresponds to the transStatus enumeration in the EMV 3-D Secure Protocol. Valid values can be Y, N, U, A, C, or R. Please see the EMV 3-D Secure Protocol spec for more information. |
| ❯ authentication_response_status | The most recent transaction status given received by the 3DS Server. This field’s value corresponds to the transStatus enumeration in the EMV 3-D Secure Protocol. Valid values can be Y, N, U, A, C, or R. Please see the EMV 3-D Secure Protocol spec for more information. |
| ❯ authentication_value | The authentication value returned by the 3DS Server for successful authentications |
| ❯ trans_status_reason | Provides information on why the authentication_response_status field has the specific value. This field’s value corresponds to the transStatusReason enumeration in the EMV 3-D Secure Protocol. Please see EMV 3-D Secure Protocol spec for more information. |
| ❯ daf | Boolean field to indicate if the authentication request utilized Visa’s Digital Authentication Framework. |
Authenticate
POST /v1/sca/providers/ZI0HsrLtnvzvNry7f3HARhnOXbA/authenticate.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"currency_code": "EUR",
"amount": 100,
"test_scenario": {
"scenario": "authenticated"
},
"browser_info": "eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ=="
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<currency_code>EUR</currency_code>
<amount>100</amount>
<test_scenario>
<scenario>authenticated</scenario>
</test_scenario>
<browser_info>
eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ==
</browser_info>
</transaction>
HTTPS/1.1 200 OK Created
{
"transaction": {
"created_at": "2022-06-03T13:12:42Z",
"updated_at": "2022-06-03T13:12:42Z",
"succeeded": true,
"state": "succeeded",
"token": "CY6TZIcvWYLObGlBvfkUQ11MVQo",
"flow_performed": "frictionless",
"message": "High confidence",
"sca_provider_key": "ZI0HsrLtnvzvNry7f3HARhnOXbA",
"amount": 100,
"currency_code": "EUR",
"ip": null,
"email": null,
"order_id": null,
"three_ds_version": "2.2.0",
"ecommerce_indicator": "05",
"authentication_value": "IShIhfLJeekndsGbtRkiMTFMRjiq",
"directory_server_transaction_id": "9957db40-48dc-4f08-b371-f20c5067738b",
"authentication_value_algorithm": null,
"directory_response_status": "Y",
"authentication_response_status": "Y",
"required_action": null,
"acs_reference_number": null,
"acs_rendering_type": null,
"acs_signed_content": null,
"acs_transaction_id": "4fad8992-2c22-4106-807e-6f95a535fc08",
"sdk_transaction_id": null,
"challenge_form": null,
"challenge_form_embed_url": null,
"three_ds_server_trans_id": "6ffac88e-cde7-4b60-8db5-0e8c44e7fa61",
"xid": null,
"enrolled": "true",
"transaction_type": "Sca::Authentication",
"gateway_transaction_key": null,
"callback_url": null,
"test_scenario": {
"scenario": "authenticated"
},
"three_ds_requestor_challenge_ind": null,
"trans_status_reason": "17",
"exemption_type": null,
"acquiring_bank_fraud_rate": null,
"warning": null
}
}
<transaction>
<created_at type="dateTime">2022-05-11T19:35:17Z</created_at>
<updated_at type="dateTime">2022-05-11T19:35:17Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>1mZp4jhdmLIcAQWd93ra0JfTIUw</token>
<flow_performed>frictionless</flow_performed>
<message>High confidence</message>
<sca_provider_key>DvubDdpnYxH4lo5JE9oQ8QOSLxX</sca_provider_key>
<amount type="integer">100</amount>
<currency_code>EUR</currency_code>
<ip nil="true"></ip>
<email nil="true"></email>
<order_id nil="true"></order_id>
<three_ds_version>2.2.0</three_ds_version>
<ecommerce_indicator>05</ecommerce_indicator>
<authentication_value>qkDLcAhUgatiGQAUGQbpqIOPQris</authentication_value>
<directory_server_transaction_id>523e7dd9-fcad-459f-8b28-61532eca05c4</directory_server_transaction_id>
<authentication_value_algorithm nil="true"></authentication_value_algorithm>
<directory_response_status>Y</directory_response_status>
<authentication_response_status>Y</authentication_response_status>
<required_action nil="true"></required_action>
<acs_reference_number nil="true"></acs_reference_number>
<acs_rendering_type nil="true"></acs_rendering_type>
<acs_signed_content nil="true"></acs_signed_content>
<acs_transaction_id>00791065-8b80-40e4-82dd-ce8884018de3</acs_transaction_id>
<sdk_transaction_id nil="true"></sdk_transaction_id>
<challenge_form nil="true"></challenge_form>
<challenge_form_embed_url nil="true"></challenge_form_embed_url>
<three_ds_server_trans_id>d410087c-e672-43b4-a825-c58b3383733e</three_ds_server_trans_id>
<xid nil="true"></xid>
<enrolled>true</enrolled>
<transaction_type>Sca::Authentication</transaction_type>
<gateway_transaction_key nil="true"></gateway_transaction_key>
<callback_url nil="true"></callback_url>
<test_scenario>
<scenario>authenticated</scenario>
</test_scenario>
<three_ds_requestor_challenge_ind nil="true"></three_ds_requestor_challenge_ind>
<trans_status_reason>17</trans_status_reason>
<exemption_type nil="true"></exemption_type>
<acquiring_bank_fraud_rate nil="true"></acquiring_bank_fraud_rate>
<warning nil="true"></warning>
</transaction>
Authenticate a given payment method and amount against provided SCA Provider Key (specified in request URL)
URL Parameters
| Parameter | Description |
|---|---|
| sca_provider_key required |
The token returned by the sca providers endpoint |
| format required |
One of json or xml |
Request body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ payment_method_token required |
The token of the payment method to use |
| ❯ currency_code optional |
The currency of the funds, as ISO 4217 alpha currency codes, e.g., USD for US dollars. |
| ❯ amount optional |
The amount to request, as an integer. E.g., 1000 for $10.00. |
| ❯ browser_info required |
Please refer to our Spreedly 3DS2 Global Integration Guide for Web, to learn how to include our Lifecycle.js library and gather the browser info data using Spreedly.ThreeDS.serialize method. |
| ❯ force_daf optional |
Boolean field that can be used to indicate if a transaction should use Visa’s DAF. For more information please refer to our 3DS2 Global DAF guide |
| ❯ test_scenario optional |
Additional fields to indicate valid 3DS2 test flow options. Please refer to our 3DS2 Global Testing Guide to learn more about testing your 3DS2 Global integration with our Test SCA Provider. |
| ❯ exemption_type optional |
Type of exemption request to reduce likelihood of a transaction being challenged. The two exemptions currently supported are low_value_exemption and transaction_risk_analysis_exemption. See our exemption guide to learn more |
| ❯ acquiring_bank_fraud_rate optional |
Additional field required if requesting a transaction_risk_analysis_exemption that details threshold for bank fraud rate. See our exemption guide to learn more |
| ❯❯ three_ds_requestor_challenge_ind optional |
Indicates whether a challenge is being requested for a 3DS2 Global transaction. |
Response Body
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.
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token uniquely identifying the transaction at Spreedly. This token can be passed into an authorize or purchase transaction via the sca_authentication_token field to automatically fill its payment_method_token and Third Party 3DS2 fields. |
| ❯ succeeded | true if the transaction request was successfully executed, false otherwise |
| ❯ state | The current state of the authentication. Valid values are succeeded, failed, and pending |
| ❯ message | A human-readable string indicating the result of the transaction |
| ❯ transaction_type | The type of transaction; contains “Sca::Authentication” for a Spreedly 3DS Global authentication |
| ❯ gateway_transaction_key | The Spreedly transaction token of the parent gateway transaction |
| ❯ sca_provider_key | The SCA Provider that was used to create the authentication |
| ❯ acs_transaction_id | The unique ID of the transaction given by the ACS server (3DS2 only) |
| ❯ three_ds_server_trans_id | The unique ID of the transaction given by the 3DS Server (3DS2 only) |
| ❯ directory_server_transaction_id | The unique ID of the transaction given by the directory server (3DS2 only) |
| ❯ xid | The transaction identifier given by the 3DS Server |
| ❯ three_ds_version | The version of 3DS that was used to authenticate the transaction |
| ❯ flow_performed | An enumerated field that denotes what flow was most recently performed. Valid values are frictionless, device_fingerprint, challenge, app_challenge, and not_authenticated. |
| ❯ ecommerce_indicator | Contains the ecommerce indicator (ECI) returned by the 3DS Server |
| ❯ directory_response_status | The transaction status given by the directory server in the initial response. This field’s value corresponds to the transStatus enumeration in the EMV 3-D Secure Protocol. Valid values can be Y, N, U, A, C, or R. Please see the EMV 3-D Secure Protocol spec for more information. |
| ❯ authentication_response_status | The most recent transaction status given received by the 3DS Server. This field’s value corresponds to the transStatus enumeration in the EMV 3-D Secure Protocol. Valid values can be Y, N, U, A, C, or R. Please see the EMV 3-D Secure Protocol spec for more information. |
| ❯ authentication_value | The authentication value returned by the 3DS Server for successful authentications |
| ❯ trans_status_reason | Provides information on why the authentication_response_status field has the specific value. This field’s value corresponds to the transStatusReason enumeration in the EMV 3-D Secure Protocol. Please see EMV 3-D Secure Protocol spec for more information. |
| ❯ daf | Boolean field to indicate if the authentication request utilized Visa’s Digital Authentication Framework. |
Deliver
POST /v1/receivers/<receiver_token>/deliver.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"delivery": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"url": "https://spreedly-echo.herokuapp.com",
"headers": "Content-Type: application/json",
"body": "{ \"product_id\": \"916598\", \"card_number\": \"{{credit_card_number}}\" }"
}
}
<delivery>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<url>https://spreedly-echo.herokuapp.com</url>
<headers>
<![CDATA[Content-Type: application/json]]>
</headers>
<body>
<![CDATA[{
"product_id":"916593",
"card_number":"{{ credit_card_number }}"
}]]>
</body>
</delivery>
HTTPS/1.1 200 OK
{
"transaction": {
"token": "NQkQlB8BpQspzTnEloIDsbG7juy",
"transaction_type": "DeliverPaymentMethod",
"state": "succeeded",
"created_at": "2017-07-27T17:55:26Z",
"updated_at": "2017-07-27T17:55:26Z",
"succeeded": true,
"message": "Succeeded!",
"url": "https://spreedly-echo.herokuapp.com",
"response": {
"status": 200,
"headers": "Date: Thu, 27 Jul 2017 17:55:26 GMT\r\nConnection: close\r\nHost: spreedly-echo.herokuapp.com\r\nAccept: */*\r\nUser_agent: spreedly-agent/Typhoeus 0.6.9\r\nX_request_id: 0df136cb-6298-4c37-9d5e-a995dce53637\r\nX_forwarded_for: 167.88.149.182\r\nX_forwarded_proto: https\r\nX_forwarded_port: 443\r\nVia: 1.1 vegur, 1.1 vegur\r\nConnect_time: 3\r\nX_request_start: 1501178126796\r\nTotal_route_time: 0\r\nX-Runtime: 0.000177\r\nServer: thin 1.6.2 codename Doc Brown",
"body": "HOST: spreedly-echo.herokuapp.com\r\nCONNECTION: close\r\nACCEPT: */*\r\nUSER_AGENT: spreedly-agent/Typhoeus 0.6.9\r\nX_REQUEST_ID: 0df136cb-6298-4c37-9d5e-a995dce53637\r\nX_FORWARDED_FOR: 167.88.149.182\r\nX_FORWARDED_PROTO: https\r\nX_FORWARDED_PORT: 443\r\nVIA: 1.1 vegur\r\nCONNECT_TIME: 3\r\nX_REQUEST_START: 1501178126796\r\nTOTAL_ROUTE_TIME: 0\r\n\r\n{ \"product_id\": \"916598\", \"card_number\": \"[FILTERED]\" }"
},
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "5FvWNRyXVLnOAVfZKUOJRgmziG0",
"hostnames": "https://spreedly-echo.herokuapp.com",
"state": "retained",
"created_at": "2017-07-27T17:55:26Z",
"updated_at": "2017-07-27T17:55:26Z",
"credentials": [
{
"name": "app-id",
"value": "1234",
"safe": "true"
},
{
"name": "app-secret",
"safe": "false"
}
]
},
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2017-07-27T17:55:26Z",
"email": "joey@example.com",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"metadata": {
"key": "string value",
"another_key": 123,
"final_key": true
},
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"bin_metadata": {
"card_brand": "DISCOVER",
"card_category": "PERSONAL",
"card_type": "CREDIT",
"issuing_bank": "DISCOVER BANK",
"issuing_country_iso_number": "840",
"issuing_country_iso_a2_code": "US",
"issuing_country_iso_a3_code": "USA",
"issuing_country_iso_name": "UNITED STATES",
"issuing_bank_phone_number": "1 (800) 347-7000",
"issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
"bin_type": "PERSONAL",
"regulated": "Y",
"max_pan_length": 19,
"message": "Successful"
},
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<token>L04jnLlUabbHw6Zr21YUEhN8WKR</token>
<transaction_type>DeliverPaymentMethod</transaction_type>
<state>succeeded</state>
<created_at type="dateTime">2017-07-27T17:55:27Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:27Z</updated_at>
<succeeded type="boolean">true</succeeded>
<message>Succeeded!</message>
<url>https://spreedly-echo.herokuapp.com</url>
<response>
<status type="integer">200</status>
<headers>
<![CDATA[Date: Thu, 27 Jul 2017 17:55:27 GMT
Connection: close
Host: spreedly-echo.herokuapp.com
Accept: */*
User_agent: spreedly-agent/Typhoeus 0.6.9
X_request_id: b00f0e1e-e2ec-41f4-938b-53dd14598da7
X_forwarded_for: 167.88.149.182
X_forwarded_proto: https
X_forwarded_port: 443
Via: 1.1 vegur, 1.1 vegur
Connect_time: 1
X_request_start: 1501178127860
Total_route_time: 0
X-Runtime: 0.000148
Server: thin 1.6.2 codename Doc Brown]]>
</headers>
<body>
<![CDATA[HOST: spreedly-echo.herokuapp.com
CONNECTION: close
ACCEPT: */*
USER_AGENT: spreedly-agent/Typhoeus 0.6.9
X_REQUEST_ID: b00f0e1e-e2ec-41f4-938b-53dd14598da7
X_FORWARDED_FOR: 167.88.149.182
X_FORWARDED_PROTO: https
X_FORWARDED_PORT: 443
VIA: 1.1 vegur
CONNECT_TIME: 1
X_REQUEST_START: 1501178127860
TOTAL_ROUTE_TIME: 0
{
"product_id":"916593",
"card_number":"[FILTERED]"
}]]>
</body>
</response>
<receiver>
<company_name>TEST</company_name>
<receiver_type>test</receiver_type>
<token>MkMQdYr2dd6OaeKj8eXC1vWTSf1</token>
<hostnames>https://spreedly-echo.herokuapp.com</hostnames>
<state>retained</state>
<created_at type="dateTime">2017-07-27T17:55:27Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:27Z</updated_at>
<credentials type="array">
<credential>
<name>app-id</name>
<value>1234</value>
<safe>true</safe>
</credential>
<credential>
<name>app-secret</name>
<safe>false</safe>
</credential>
</credentials>
</receiver>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2017-07-27T17:55:27Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<metadata>
<key>String Value</key>
<another_key>123</another_key>
<final_key>true</final_key>
</metadata>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"></address1>
<address2 nil="true"></address2>
<city nil="true"></city>
<state nil="true"></state>
<zip nil="true"></zip>
<country nil="true"></country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<bin_metadata>
<card_brand>DISCOVER</card_brand>
<card_category>PERSONAL</card_category>
<card_type>CREDIT</card_type>
<issuing_bank>DISCOVER BANK</issuing_bank>
<issuing_country_iso_number>840</issuing_country_iso_number>
<issuing_country_iso_a2_code>US</issuing_country_iso_a2_code>
<issuing_country_iso_a3_code>USA</issuing_country_iso_a3_code>
<issuing_country_iso_name>UNITED STATES</issuing_country_iso_name>
<issuing_bank_phone_number>1 (800) 347-7000</issuing_bank_phone_number>
<issuing_bank_website>HTTPS://WWW.DISCOVER.COM/</issuing_bank_website>
<bin_type>PERSONAL</bin_type>
<regulated>Y</regulated>
<max_pan_length>19</max_pan_length>
<message>Successful</message>
</bin_metadata>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Deliver a payment method to the specified receiver endpoint. See the guide on payment method distribution to understand how to specify what is sent to the receiver. Spreedly provides an open repository of code templates for simplifying implementation of new receivers.
URL Parameters
| Parameter | Description |
|---|---|
| receiver_token required |
The token of the receiver at Spreedly |
| format required |
One of json or xml |
Request Body
| Parameter | Description |
|---|---|
| delivery | Root element |
| ❯ continue_caching | An option to keep the cvv cached for a few minutes. Otherwise cvv is deleted immediately. |
| ❯ payment_method_token required |
The token of the payment method to send to the receiver and whose values will be applied to the delivery template |
| ❯ url required |
The fully qualified URL to send the payment method. The URL must have the same hostname as one of the allowed hostnames for the target receiver. The URL string can include distribution variable placeholders, e.g., https://prod.receiver.com/path/book?user={{ user_name }}. |
| ❯ request_method | An option to specify the HTTP method to use when contacting the receiver. Acceptable values are PUT, PATCH, and POST. If omitted, the default value is POST. |
| ❯ headers | The request headers to be sent to the receiver as a colon-delimited, new-line separated, string. Host and Content-Length can be omitted as they are automatically generated by Spreedly. Headers can include distribution variable placeholders, e.g., User: {{ user_name }}. |
| ❯ body required |
The request body that will get sent to the receiver. The body can include distribution variable placeholders, e.g., <cardNumber>{{ credit_card_number }}</cardNumber>. |
| ❯ encode_response default: false |
If true, the response_body value in the delivery transaction response will be base64 encoded. This is useful if there are characters in the response known to cause encoding or other formatting issues. |
| ❯ sub_merchant_key | The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token of this transaction |
| ❯ succeeded | If the delivery request completed with a non-error HTTP status (2XX) |
| ❯ message | A brief description of the result of the transaction |
| ❯ response | The raw response status, header and body returned from the receiver. Parse these values to retrieve relevant response fields. |
| ❯❯ status | The status code returned by the receiver. |
| ❯❯ headers | The headers, as delivered exactly by the receiver. |
| ❯❯ body | The raw body delivered from the receiver, with account numbers and sensitive data redacted. |
| ❯ receiver | The receiver the payment method was delivered to |
| ❯ payment_method | The payment_method sent to the receiver |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
A successful (HTTP 200) response from the Spreedly API indicates that Spreedly was able to successfully communicate with the receiver (response code < 400 ), it does not indicate that the final status at the endpoint. You must check the status field of the response element to see the actual status code from the receiver endpoint.
BIN metadata is available in the response if the card is enrolled in Advanced Vault. See BIN metadata for more information.
Export
POST /v1/receivers/UKjXqMKs10ChhaB83j6uLjUbb2U/export.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"export": {
"payment_method_tokens": [
"56wyNnSmuA6CWYP7w0MiYCVIbW6",
"TtSvidJm3e4Lmza4l8Je5Bwuqmf"
],
"url": "sftp://testserver.com/path/to/filename.txt",
"callback_url": "https://yoursite.com/spreedly/tx_callback",
"body": "{ \"cards\": [{{#payment_methods}}\"{{credit_card_number}}\",{{/payment_methods}}] }"
}
}
Export does not support the xml format.
HTTPS/1.1 202 Accepted
{
"transaction": {
"token": "GZ9ylkvYKQKp440LLgTxhSORpx0",
"transaction_type": "ExportPaymentMethods",
"state": "pending",
"created_at": "2018-04-20T14:04:55Z",
"updated_at": "2018-04-20T14:04:55Z",
"succeeded": false,
"message": "Pending",
"payment_methods_submitted": [
"1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"PUijKEvAOllfOqTAu2ZDeSaAfjc"
],
"payment_method_data": null,
"payment_methods_included": null,
"encode_response": null,
"callback_url": "https://yoursite.com/spreedly/tx_callback",
"url": "sftp://testserver.com/path/to/filename.txt",
"payment_methods_excluded": null,
"response": {
"status": null
},
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "MZjXWBFfixaYncOUJZKdpj8KnG4",
"hostnames": "sftp://testserver.com",
"state": "retained",
"created_at": "2018-04-20T14:04:55Z",
"updated_at": "2018-04-20T14:04:55Z",
"credentials": null,
"protocol": {
"user": "user"
}
}
}
}
Export multiple payment methods in a single, asynchronous, batch call to an SFTP receiver endpoint.
URL Parameters
| Parameter | Description |
|---|---|
| receiver_token required |
The token of the receiver at Spreedly |
| format required |
json (xml is currently unsupported) |
Request Body
| Parameter | Description |
|---|---|
| export | Root element |
| ❯ payment_method_tokens required |
An array of payment method tokens to include in the export. |
| ❯ payment_method_data optional |
A hash of key/value pairs. For each pair, the key is a payment_method_token and the value is a hash of information specific to the associated payment method. This payment method specific information is made available to the request template at time of export. |
| ❯ url required |
The fully qualified URL for the SFTP server. The URL must have the same hostname as one of the allowed hostnames for the target receiver. The path of the url will be used as the file name, e.g., sftp://prod.receiver.com/path/to/file.txt. |
| ❯ body required |
The request body that will get sent to the receiver e.g., {{#payment_methods}} <cardNumber>{{ credit_card_number }}</cardNumber> {{/payment_methods}}. |
| ❯ callback_url optional |
The url where Spreedly will attempt delivery of transaction results. Transaction results are posted in JSON format. |
| ❯ sub_merchant_key optional |
The token of the sub-merchant to associate with the current transaction. If an invalid sub_merchant_key is passed through, the value defaults to null |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ token | The token of this transaction |
| ❯ state | The state of this transaction. The state will be “pending” until the transaction has completed processing. Once processed, the state can be either “succeeded” or “failed” |
| ❯ succeeded |
Shows if the transaction completed with a non error status. While the transaction is pending, this value will be false. |
| ❯ message | A brief description of the results of the transaction. |
| ❯ response | The response status returned from the receiver. The response is null while the transaction is pending. |
| ❯ receiver | The receiver the payment method was exported to |
| ❯ sub_merchant_key | The token of the sub-merchant associated with the transaction. |
| ❯ payment_methods_submitted | The payment method tokens in the original export request |
| ❯ payment_methods_included | The payment method tokens included in the export to the receiver. This value is null while the transaction is pending. Once the transaction is processed, this value will be an array of payment method tokens. |
| ❯ payment_methods_excluded | The payment methods that were not included in the export to the receiver. The value is null while the transaction is pending. Once the transaction is processed, this value will be a hash with key/value pairs. The keys are payment method tokens, the values are the reason the payment method was not included in the export to the receiver. |
w/ Additional data
POST /v1/receivers/UKjXqMKs10ChhaB83j6uLjUbb2U/export.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"export": {
"payment_method_tokens": [
"56wyNnSmuA6CWYP7w0MiYCVIbW6",
"TtSvidJm3e4Lmza4l8Je5Bwuqmf"
],
"url": "sftp://testserver.com/path/to/filename.txt",
"callback_url": "https://yoursite.com/spreedly/tx_callback",
"body": "{ \"cards\": [ {{#payment_methods}}{\"number\": \"{{credit_card_number}}\", \"orderId\": \"{{ order_id }}\"},{{/payment_methods}} ] }",
"payment_method_data": {
"56wyNnSmuA6CWYP7w0MiYCVIbW6": {
"order_id": "1234"
},
"TtSvidJm3e4Lmza4l8Je5Bwuqmf": {
"order_id": "5678"
}
}
}
}
Export does not support the xml format.
HTTPS/1.1 202 Accepted
{
"transaction": {
"token": "Pfl0xPOajyhd4qFHCEmwMLDQT7K",
"transaction_type": "ExportPaymentMethods",
"state": "pending",
"created_at": "2018-04-20T12:58:02Z",
"updated_at": "2018-04-20T12:58:02Z",
"succeeded": false,
"message": "Pending",
"payment_methods_submitted": [
"1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"PUijKEvAOllfOqTAu2ZDeSaAfjc"
],
"payment_method_data": {
"1rpKvP8zOUhj4Y9EDrIoIYQzzD5": {
"order_id": "1234"
},
"PUijKEvAOllfOqTAu2ZDeSaAfjc": {
"order_id": "5678"
}
},
"payment_methods_included": null,
"encode_response": null,
"callback_url": "https://yoursite.com/spreedly/tx_callback",
"url": "sftp://testserver.com/path/to/filename.txt",
"payment_methods_excluded": null,
"response": {
"status": null
},
"receiver": {
"company_name": "TEST",
"receiver_type": "test",
"token": "ILzWoG6bXG0XqFnXXYpN50Drw25",
"hostnames": "sftp://testserver.com",
"state": "retained",
"created_at": "2018-04-20T12:58:01Z",
"updated_at": "2018-04-20T12:58:01Z",
"credentials": null,
"protocol": {
"user": "user"
}
}
}
}
To associate card-specific properties (not exposed as template variables), use the payment_method_data property to specify variables tied to specific payment method tokens.
Environments
Create environment
POST /v1/environments.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"environment": {
"name": "Test Environment",
"allow_direct_api_payment_method_creation": false
}
}
<environment>
<name>Test Environment</name>
<allow_direct_api_payment_method_creation type="boolean">false</allow_direct_api_payment_method_creation>
</environment>
HTTPS/1.1 201 Created
{
"environment": {
"key": "<key>",
"signing_secret": "<signing_secret>",
"organization_key": "<organization_key>",
"callback_url": null,
"smart_routing_enabled": false,
"au_enabled": false,
"allow_direct_api_payment_method_creation": false,
"name": "Test Environment",
"default_gateway_token": null,
"payment_method_management_enabled": true
}
}
<environment>
<key>{key}</key>
<signing_secret>{signing_secret}</signing_secret>
<organization_key>{organization_key}</organization_key>
<name>Test Environment</name>
<callback_url nil="true"></callback_url>
<smart_routing_enabled type="boolean">false</smart_routing_enabled>
<default_gateway_token nil="true"></default_gateway_token>
<au_enabled type="boolean">false</au_enabled>
<allow_direct_api_payment_method_creation type="boolean">false</allow_direct_api_payment_method_creation>
<payment_method_management_enabled type="boolean">true</payment_method_management_enabled>
</environment>
Create an environment in your organization.
You will need to create one environment manually at id.spreedly.com for authentication. After that you can authenticate the API call using that environment key and an Organization Access Secret
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| environment | Root element |
| ❯ name required 100 character limit can’t contain \ | ` # $ % { } ; " < > |
The human readable name of the environment |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. (default: null) |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe (default: true) |
| ❯ au_enabled | If the environment should have cards sent to Account Updater or not (default: false) |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| environment | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ organization_key | The organization that the environment belongs to |
| ❯ smart_routing_enabled | If the environment has smart routing enabled or not |
| ❯ default_gateway_token | The default gateway to send transactions if smart routing is enabled |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe |
| ❯ signing_secret | The secret used to sign callbacks that are made back into your application |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
Show environment
GET /v1/environments/<environment_key>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"environment": {
"key": "<key>",
"signing_secret": "<signing_secret>",
"organization_key": "<organization_key>",
"callback_url": null,
"smart_routing_enabled": false,
"allow_direct_api_payment_method_creation": false,
"name": "New Environment Name",
"default_gateway_token": null,
"payment_method_management_enabled": true
}
}
<environment>
<key>{key}</key>
<signing_secret>{signing_secret}</signing_secret>
<organization_key>{organization_key}</organization_key>
<stripe_user_id nil="true"></stripe_user_id>
<name>New Environment Name</name>
<callback_url nil="true"></callback_url>
<smart_routing_enabled type="boolean">false</smart_routing_enabled>
<default_gateway_token nil="true"></default_gateway_token>
<allow_direct_api_payment_method_creation type="boolean">false</allow_direct_api_payment_method_creation>
<payment_method_management_enabled type="boolean">true</payment_method_management_enabled>
</environment>
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.
URL Parameters
| Parameter | Description |
|---|---|
| environment_key required |
The key of the environment to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| environment | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ organization_key | The organization that the environment belongs to |
| ❯ smart_routing_enabled | If the environment has smart routing enabled or not |
| ❯ default_gateway_token | The default gateway to send transactions if smart routing is enabled |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe |
| ❯ signing_secret | The secret used to sign callbacks that are made back into your application |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
List environments
GET /v1/environments.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"environments": [
{
"key": "<key>",
"signing_secret": "<signing_secret>",
"organization_key": "<organization_key>",
"callback_url": "https://www.google.com",
"smart_routing_enabled": false,
"allow_direct_api_payment_method_creation": false,
"name": "<name>",
"default_gateway_token": "",
"payment_method_management_enabled": true
},
{
"key": "<key>",
"signing_secret": "<signing_secret>",
"organization_key": "<organization_key>",
"callback_url": "",
"smart_routing_enabled": true,
"allow_direct_api_payment_method_creation": true,
"name": "<name>",
"default_gateway_token": "<default_gateway_token>",
"payment_method_management_enabled": true
}
]
}
<environments>
<environment>
<key>{key}</key>
<signing_secret>{signing_secret}</signing_secret>
<organization_key>{organization_key}</organization_key>
<name>{name}</name>
<callback_url>https://www.google.com</callback_url>
<smart_routing_enabled type="boolean">false</smart_routing_enabled>
<default_gateway_token>{default_gateway_token}</default_gateway_token>
<allow_direct_api_payment_method_creation type="boolean">false</allow_direct_api_payment_method_creation>
<payment_method_management_enabled type="boolean">true</payment_method_management_enabled>
</environment>
<environment>
<key>{key}</key>
<signing_secret>{signing_secret}</signing_secret>
<organization_key>{organization_key}</organization_key>
<name>{name}</name>
<callback_url></callback_url>
<smart_routing_enabled type="boolean">true</smart_routing_enabled>
<default_gateway_token>{default_gateway_token}</default_gateway_token>
<allow_direct_api_payment_method_creation type="boolean">true</allow_direct_api_payment_method_creation>
<payment_method_management_enabled type="boolean">true</payment_method_management_enabled>
</environment>
</environments>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | Token refers to the key of the environment to start from (e.g., the last environment_key received in the previous list if iterating through records) |
| count | The number of environments to return. By default returns 20, maximum allowed is 100. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| environments | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ organization_key | The organization that the environment belongs to |
| ❯ smart_routing_enabled | If the environment has smart routing enabled or not |
| ❯ default_gateway_token | The default gateway to send transactions if smart routing is enabled |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe |
| ❯ signing_secret | The secret used to sign callbacks that are made back into your application |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
Update environment
PUT /v1/environments/<environment_key>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"environment": {
"name": "Updated Environment"
}
}
<environment>
<name>Updated Environment</name>
</environment>
HTTPS/1.1 200 OK
{
"environment": {
"key": "<key>",
"signing_secret": "<signing_secret>",
"organization_key": "<organization_key>",
"callback_url": null,
"smart_routing_enabled": false,
"au_enabled": false,
"allow_direct_api_payment_method_creation": false,
"name": "Updated Environment",
"default_gateway_token": null,
"payment_method_management_enabled": true
}
}
<environment>
<key>{key}</key>
<signing_secret>{signing_secret}</signing_secret>
<organization_key>{organization_key}</organization_key>
<name>Updated Environment</name>
<callback_url nil="true"></callback_url>
<smart_routing_enabled type="boolean">false</smart_routing_enabled>
<default_gateway_token nil="true"></default_gateway_token>
<au_enabled type="boolean">false</au_enabled>
<allow_direct_api_payment_method_creation type="boolean">false</allow_direct_api_payment_method_creation>
<payment_method_management_enabled type="boolean">true</payment_method_management_enabled>
</environment>
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.
URL Parameters
| Parameter | Description |
|---|---|
| environment_key required |
The key of the environment to execute against |
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| environment | Root element |
| ❯ name 100 character limit can’t contain \ | ` # $ % { } ; " < > |
The human readable name of the environment |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. (default: null) |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe (default: true) |
| ❯ au_enabled | If the environment should have cards sent to Account Updater or not (default: false) |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
| ❯ smart_routing_enabled | If the environment has smart routing enabled or not (default: false) |
| ❯ default_gateway_token | The default gateway to send transactions if smart routing is enabled (default: null) |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| environment | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ organization_key | The organization that the environment belongs to |
| ❯ smart_routing_enabled | If the environment has smart routing enabled or not |
| ❯ default_gateway_token | The default gateway to send transactions if smart routing is enabled |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe |
| ❯ signing_secret | The secret used to sign callbacks that are made back into your application |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
Regenerate signing secret
POST /v1/environments/<environment_key>/regenerate_signing_secret.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"environment": {
"key": "<key>",
"signing_secret": "<signing_secret>",
"organization_key": "<organization_key>",
"callback_url": null,
"smart_routing_enabled": false,
"allow_direct_api_payment_method_creation": false,
"name": "New Environment Name",
"default_gateway_token": null,
"payment_method_management_enabled": true
}
}
<environment>
<key>{key}</key>
<signing_secret>{signing_secret}</signing_secret>
<organization_key>{organization_key}</organization_key>
<stripe_user_id nil="true"></stripe_user_id>
<name>New Environment Name</name>
<callback_url nil="true"></callback_url>
<smart_routing_enabled type="boolean">false</smart_routing_enabled>
<default_gateway_token nil="true"></default_gateway_token>
<allow_direct_api_payment_method_creation type="boolean">false</allow_direct_api_payment_method_creation>
<payment_method_management_enabled type="boolean">true</payment_method_management_enabled>
</environment>
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.
URL Parameters
| Parameter | Description |
|---|---|
| environment_key required |
The key of the environment to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| environment | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ organization_key | The organization that the environment belongs to |
| ❯ smart_routing_enabled | If the environment has smart routing enabled or not |
| ❯ default_gateway_token | The default gateway to send transactions if smart routing is enabled |
| ❯ callback_url | The url where Spreedly will attempt delivery of account updater transaction results. Transaction results are posted in JSON format. |
| ❯ allow_direct_api_payment_method_creation | If the environment allows payment method creation from anywhere, or only from Spreedly Express or Iframe |
| ❯ signing_secret | The secret used to sign callbacks that are made back into your application |
| ❯ payment_method_management_enabled | If an environment is enabled to manage payment methods with Advanced Vaulting |
Access Secrets
Create access secret
POST /v1/environments/<environment_key>/access_secrets.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"access_secret": {
"name": "New Access Secret"
}
}
<access_secret>
<name>New Access Secret</name>
</access_secret>
HTTPS/1.1 201 Created
{
"access_secret": {
"key": "<key>",
"name": "New Access Secret",
"environment": "Updated Environment",
"access_secret": "<access_secret>",
"created_at": "2021-12-13T21:19:01Z"
}
}
<access_secret>
<key>{key}</key>
<name>New Access Secret</name>
<environment>Updated Environment</environment>
<access_secret>{access_secret}</access_secret>
<created_at>2021-12-13T21:19:01Z</created_at>
</access_secret>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request Body
| Element | Description |
|---|---|
| access_secret | Root element |
| ❯ name required 100 character limit can’t contain \ | ` # $ % { } ; " < > |
The human readable name of the access_secret |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| access_secret | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ environment | The name of the environment that the access_secret belongs to |
| ❯ created_at | The access secret’s created_at date e.g. 2016-07-13 14:14:03 UTC |
Show access secret
GET /v1/environments/<environment_key>/access_secrets/<access_secret_key>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 200 OK
{
"access_secret": {
"key": "<key>",
"name": "New Access Secret",
"environment": "Updated Environment",
"access_secret": "<access_secret>",
"created_at": "2021-12-13T21:19:01Z"
}
}
<access_secret>
<key>{key}</key>
<name>New Access Secret</name>
<environment>Updated Environment</environment>
<access_secret>{access_secret}</access_secret>
<created_at>2021-12-13T21:19:01Z</created_at>
</access_secret>
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.
URL Parameters
| Parameter | Description |
|---|---|
| environment_key required |
The key of the environment to execute against |
| access_secret_key required |
The key of the access_secret to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| access_secret | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ environment | The name of the environment that the access_secret belongs to |
| ❯ created_at | The access secret’s created_at date e.g. 2016-07-13 14:14:03 UTC |
| ❯ access_secret | The access secret value |
List access secrets
GET /v1/environments/<environment_key>/access_secrets.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"access_secrets": [
{
"key": "<key>",
"name": "My Secret",
"environment": "Updated Environment",
"created_at": "2021-12-13T18:25:37Z"
},
{
"key": "<key>",
"name": "Another Secret",
"environment": "Updated Environment",
"created_at": "2021-12-13T18:26:56Z"
}
]
}
<access_secrets>
<access_secret>
<key>{key}</key>
<name>My Secret</name>
<environment>Updated Environment</environment>
<created_at>2021-12-13T18:25:37Z</created_at>
</access_secret>
<access_secret>
<key>{key}</key>
<name>Another Secret</name>
<environment>Updated Environment</environment>
<created_at>2021-12-13T18:26:56Z</created_at>
</access_secret>
</access_secrets>
Retrieve an 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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| access_secrets | Root element |
| ❯ key | The key identifying the environment at Spreedly |
| ❯ name | The human readable name of the environment |
| ❯ environment | The name of the environment that the access_secret belongs to |
| ❯ created_at | The access secret’s created_at date e.g. 2016-07-13 14:14:03 UTC |
Delete access secret
DELETE /v1/environments/<environment_key>/access_secrets/<access_secret_key>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
HTTPS/1.1 204 No Content
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Sub-merchants
Create sub-merchant
POST /v1/sub_merchants.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"sub_merchant": {
"name": "My Submerchant name",
"environment_key": "<environment_key>",
"merchant_url": "www.submerchanturl.com",
"merchant_email": "example@email.com",
"ein": "12-3456789",
"merchant_defined_uid": "abcd1234",
"merchant_data": [
{
"card_network": "visa",
"acquirer_merchant_id": "sub-merchants mid",
"mcc": "5978",
"acquirer_bin": "4444444444",
"business_id": "7654321"
}
],
"address": {
"address1": "100 Main Street",
"city": "Funk",
"state": "NE",
"zip": "68940",
"country": "US"
},
"metadata": {
"custom_key": "custom_value"
}
}
}
<sub_merchant>
<name>My Submerchants name</name>
<environment_key>{environment_key}</environment_key>
<merchant_url>www.submerchanturl.com</merchant_url>
<merchant_email>example@email.com</merchant_email>
<ein>12-3456789</ein>
<merchant_defined_uid>abcd1234</merchant_defined_uid>
<merchant_data type="array">
<value>
<card_network>visa</card_network>
<acquirer_merchant_id>sub-merchant mid</acquirer_merchant_id>
<mcc>5978</mcc>
<acquirer_bin>4444444444</acquirer_bin>
<business_id>7654321</business_id>
</value>
</merchant_data>
<address>
<address1>100 Main Street</address1>
<city>Funk</city>
<state>NE</state>
<zip>68940</zip>
<country>US</country>
</address>
<metadata>
<custom_key>custom_value</custom_key>
</metadata>
</sub_merchant>
HTTPS/1.1 200 OK Created
{
"sub_merchant": {
"token": "<token>",
"name": "My Submerchant name",
"environment_key": "<environment_key>",
"organization_key": "<organization_key>",
"merchant_url": "www.submerchanturl.com",
"merchant_email": "example@email.com",
"ein": "12-3456789",
"merchant_defined_uid": "abcd1234",
"merchant_data": [
{
"card_network": "visa",
"acquirer_merchant_id": "sub-merchants mid",
"mcc": "5978",
"acquirer_bin": "4444444444",
"business_id": "7654321",
"merchant_data_id": "eb6c582c-6a5f-4e1d-accf-5874574c81e1"
}
],
"address": {
"address1": "100 Main Street",
"city": "Funk",
"state": "NE",
"zip": "68940",
"country": "US"
},
"metadata": {
"custom_key": "custom_value"
},
"created_at": "2022-08-09T15:35:46Z",
"updated_at": "2022-08-09T15:35:46Z"
}
}
<sub_merchant>
<token>{token}</token>
<name>My Submerchants name</name>
<environment_key>{environment_key}</environment_key>
<organization_key>{organization_key}</organization_key>
<merchant_url>www.submerchanturl.com</merchant_url>
<merchant_email>example@email.com</merchant_email>
<ein>12-3456789</ein>
<merchant_defined_uid>abcd1234</merchant_defined_uid>
<address>
<address1>100 Main Street</address1>
<city>Funk</city>
<state>NE</state>
<zip>68940</zip>
<country>US</country>
</address>
<metadata>
<custom_key>custom_value</custom_key>
</metadata>
<created_at type="dateTime">2022-08-09T15:35:46Z</created_at>
<updated_at type="dateTime">2022-08-09T15:35:46Z</updated_at>
<merchant_data type="array">
<merchant_datum>
<merchant_data_id>91b4b725-3916-453e-ad29-b8b000cb2ae2</merchant_data_id>
<card_network>visa</card_network>
<acquirer_merchant_id>sub-merchant mid</acquirer_merchant_id>
<mcc>5978</mcc>
<acquirer_bin>4444444444</acquirer_bin>
<business_id>7654321</business_id>
</merchant_datum>
</merchant_data>
</sub_merchant>
Create a sub-merchant
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
Request body
| Parameter | Description |
|---|---|
| sub_merchant | Root Element |
| ❯ name required |
The human readable name of the sub_merchant |
| ❯ environment_key required |
The key of the environment that the sub_merchant should be associated with |
| ❯ merchant_url | The merchant’s website url. |
| ❯ merchant_email | The email address associated with the merchant |
| ❯ ein | The employer identification number associated with the merchant |
| ❯ merchant_defined_uid | A string value that can be set on the sub_merchant to help identify the sub_merchant in systems external to Spreedly. |
| ❯ merchant_data | An array of objects to store more information about the merchant |
| ❯❯ card_network | The merchant data fields can be different depending on the card network. So, this field is to identify the network associated with the other fields in a merchant_data object. |
| ❯❯ acquirer_merchant_id required only if merchant_data present |
The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ acquirer_bin | The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ business_id | The merchant’s business, company, or service identifier specific to the card-network |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯ address | The address associated with the merchant |
| ❯❯ address1 | The first line of the merchant’s address |
| ❯❯ address2 | The second line of the merchant’s address |
| ❯❯ city | The city of the merchant’s address |
| ❯❯ state | The state of the merchant’s address |
| ❯❯ zip | The zip code of the merchant’s address |
| ❯❯ country | The Country Code in ISO 3166-1 numeric format of the merchant’s address |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| sub_merchant | Root element |
| ❯ token | The token identifying the sub_merchant at Spreedly |
| ❯ name | The human readable name of the sub_merchant |
| ❯ organization_key | The organization that the sub_merchant belongs to |
| ❯ environment_key | The environment that the sub_merchant is associated with |
| ❯ merchant_url | The merchant’s website url. |
| ❯ merchant_email | The email address associated with the merchant |
| ❯ ein | The employer identification number associated with the merchant |
| ❯ merchant_defined_uid | A string value that can be set on the sub_merchant to help identify the sub_merchant in systems external to spreedly. |
| ❯ merchant_data | An array of objects to store more information about the merchant |
| ❯❯ card_network | The merchant data fields can be different depending on the card network. So, this field is to identify the network associated with the other fields in a merchant_data object. |
| ❯❯ aquirer_merchant_id | The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ acquirer_bin | The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ business_id | The merchant’s business, company, or service identifier specific to the card-network |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯❯ merchant_data_id | Spreedly generated id for each merchant_data element |
| ❯ address | The address associated with the merchant |
| ❯❯ address1 | The first line of the merchant’s address |
| ❯❯ address2 | The second line of the merchant’s address |
| ❯❯ city | The city of the merchant’s address |
| ❯❯ state | The state of the merchant’s address |
| ❯❯ zip | The zip code of the merchant’s address |
| ❯❯ country | The Country Code in ISO 3166-1 numeric format of the merchant’s address |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
| ❯ created_at | The datetime that the sub_merchant was first created |
| ❯ updated_at | The datetime that the sub_merchant was last updated |
Show sub-merchant
GET /v1/sub_merchants/<sub_merchant_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 OK
{
"sub_merchant": {
"token": "<token>",
"name": "Updated submerchant name",
"environment_key": "<environment_key>",
"organization_key": "<organization_key>",
"merchant_url": "www.submerchanturl.com",
"merchant_email": "new@email.com",
"ein": "12-3456789",
"merchant_defined_uid": "abcd1234",
"merchant_data": [
{
"card_network": "visa",
"acquirer_merchant_id": "sub-merchant mid",
"mcc": "5978",
"acquirer_bin": "4444444444",
"business_id": "7654321",
"merchant_data_id": "0887fd7b-729a-49d3-8232-4294a262a33e"
}
],
"address": {
"address1": "100 Main Street",
"city": "Funk",
"state": "NE",
"zip": "68940",
"country": "US"
},
"metadata": null,
"created_at": "2022-08-05T17:52:28Z",
"updated_at": "2022-08-08T15:05:51Z"
}
}
<sub_merchant>
<token>{token}</token>
<name>My Submerchants name</name>
<environment_key>{environment_key}</environment_key>
<organization_key>{organization_key}</organization_key>
<merchant_url>www.submerchanturl.com</merchant_url>
<merchant_email>example@email.com</merchant_email>
<ein>12-3456789</ein>
<merchant_defined_uid>abcd1234</merchant_defined_uid>
<address>
<address1>100 Main Street</address1>
<city>Funk</city>
<state>NE</state>
<zip>68940</zip>
<country>US</country>
</address>
<metadata>
<custom_key>custom_value</custom_key>
</metadata>
<created_at type="dateTime">2022-08-09T15:35:46Z</created_at>
<updated_at type="dateTime">2022-08-09T15:35:46Z</updated_at>
<merchant_data type="array">
<merchant_datum>
<merchant_data_id>91b4b725-3916-453e-ad29-b8b000cb2ae2</merchant_data_id>
<card_network>visa</card_network>
<acquirer_merchant_id>sub-merchant mid</acquirer_merchant_id>
<mcc>5978</mcc>
<acquirer_bin>4444444444</acquirer_bin>
<business_id>7654321</business_id>
</merchant_datum>
</merchant_data>
</sub_merchant>
Get the sub-merchant with the given key.
URL Parameters
| Parameter | Description |
|---|---|
| sub_merchant_key required |
The key of the sub-merchant to execute against |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| sub_merchant | Root element |
| ❯ token | The token identifying the sub_merchant at Spreedly |
| ❯ name | The human readable name of the sub_merchant |
| ❯ organization_key | The organization that the sub_merchant belongs to |
| ❯ environment_key | The environment that the sub_merchant is associated with |
| ❯ merchant_url | The merchant’s website url. |
| ❯ merchant_email | The email address associated with the merchant |
| ❯ ein | The employer identification number associated with the merchant |
| ❯ merchant_defined_uid | A string value that can be set on the sub_merchant to help identify the sub_merchant in systems external to spreedly. |
| ❯ merchant_data | An array of objects to store more information about the merchant |
| ❯❯ card_network | The merchant data fields can be different depending on the card network. So, this field is to identify the network associated with the other fields in a merchant_data object. |
| ❯❯ aquirer_merchant_id | The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ acquirer_bin | The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ business_id | The merchant’s business, company, or service identifier specific to the card-network |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯❯ merchant_data_id | Spreedly generated id for each merchant_data element |
| ❯ address | The address associated with the merchant |
| ❯❯ address1 | The first line of the merchant’s address |
| ❯❯ address2 | The second line of the merchant’s address |
| ❯❯ city | The city of the merchant’s address |
| ❯❯ state | The state of the merchant’s address |
| ❯❯ zip | The zip code of the merchant’s address |
| ❯❯ country | The Country Code in ISO 3166-1 numeric format of the merchant’s address |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
| ❯ created_at | The datetime that the sub_merchant was first created |
| ❯ updated_at | The datetime that the sub_merchant was last updated |
List sub-merchants
GET /v1/sub_merchants.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Example response has been truncated for brevity
HTTPS/1.1 200 OK
{
"sub_merchants": [
{
"token": "<token>",
"name": "Test Sub Merchant",
"environment_key": "<environment_key>",
"organization_key": "<organization_key>",
"merchant_url": "https://www.do.biz",
"merchant_email": "is@fake.com",
"ein": "98-7654321",
"merchant_defined_uid": "abc-123",
"merchant_data": [
{
"card_network": "mastercard",
"acquirer_merchant_id": "xxxxxxxxxx",
"mcc": "5978",
"acquirer_bin": "4444444444",
"business_id": "1234567",
"merchant_data_id": "934549d5-0dc4-4aa9-8142-389c73a8c0bf"
}
],
"address": null,
"metadata": null,
"created_at": "2022-05-18T17:00:05Z",
"updated_at": "2022-08-08T15:13:45Z"
},
{
"token": "<token>",
"name": "My Sub-merchant's name",
"environment_key": "<environment_key>",
"organization_key": "<organization_key>",
"merchant_url": "www.mysubmerchantsurl.com",
"merchant_email": "example@email.com",
"ein": "12-3456789",
"merchant_defined_uid": "abcd-1234",
"merchant_data": [
{
"card_network": "visa",
"acquirer_merchant_id": "sub-merchants mid",
"mcc": "5978",
"acquirer_bin": "4444444444",
"business_id": "7654321",
"merchant_data_id": "c7028777-5eab-455e-ae1a-2de35d2a6734"
}
],
"address": {
"address1": "100 Main Street",
"city": "Funk",
"state": "NE",
"zip": "68940",
"country": "US"
},
"metadata": null,
"created_at": "2022-05-31T20:11:04Z",
"updated_at": "2022-08-08T15:14:23Z"
}
]
}
<sub_merchants>
<sub_merchant>
<token>{token}</token>
<name>Test Sub Merchant</name>
<environment_key>{environment_key}</environment_key>
<organization_key>{organization_key}</organization_key>
<merchant_url>https://www.do.biz</merchant_url>
<merchant_email>is@fake.com</merchant_email>
<ein>98-7654321</ein>
<merchant_defined_uid>abc-123</merchant_defined_uid>
<address nil="true"></address>
<metadata nil="true"></metadata>
<created_at type="dateTime">2022-05-18T17:00:05Z</created_at>
<updated_at type="dateTime">2022-08-08T15:13:45Z</updated_at>
<merchant_data type="array">
<merchant_datum>
<merchant_data_id>934549d5-0dc4-4aa9-8142-389c73a8c0bf</merchant_data_id>
<card_network>mastercard</card_network>
<acquirer_merchant_id>xxxxxxxxxx</acquirer_merchant_id>
<mcc>5978</mcc>
<acquirer_bin>4444444444</acquirer_bin>
<business_id>1234567</business_id>
</merchant_datum>
</merchant_data>
</sub_merchant>
<sub_merchant>
<token>{token}</token>
<name>My Sub-merchant's name</name>
<environment_key>{environment_key}</environment_key>
<organization_key>{organization_key}</organization_key>
<merchant_url>www.mysubmerchantsurl.com</merchant_url>
<merchant_email>example@email.com</merchant_email>
<ein>12-3456789</ein>
<merchant_defined_uid>abcd-1234</merchant_defined_uid>
<address>
<address1>100 Main Street</address1>
<city>Funk</city>
<state>NE</state>
<zip>68940</zip>
<country>US</country>
</address>
<metadata nil="true"></metadata>
<created_at type="dateTime">2022-05-31T20:11:04Z</created_at>
<updated_at type="dateTime">2022-08-08T15:14:23Z</updated_at>
<merchant_data type="array">
<merchant_datum>
<merchant_data_id>c7028777-5eab-455e-ae1a-2de35d2a6734</merchant_data_id>
<card_network>visa</card_network>
<acquirer_merchant_id>sub-merchants mid</acquirer_merchant_id>
<mcc>5978</mcc>
<acquirer_bin>4444444444</acquirer_bin>
<business_id>7654321</business_id>
</merchant_datum>
</merchant_data>
</sub_merchant>
</sub_merchants>
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.
URL Parameters
| Parameter | Description |
|---|---|
| format required |
One of json or xml |
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
| since_token | The token of the item to start from (e.g., the last token received in the previous list if iterating through records) |
| count | The number of sub_merchants to return. By default returns 20, maximum allowed is 100. |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| sub_merchants | Root element |
| ❯ token | The token identifying the sub_merchant at Spreedly |
| ❯ name | The human readable name of the sub_merchant |
| ❯ organization_key | The organization that the sub_merchant belongs to |
| ❯ environment_key | The environment that the sub_merchant is associated with |
| ❯ merchant_url | The merchant’s website url. |
| ❯ merchant_email | The email address associated with the merchant |
| ❯ ein | The employer identification number associated with the merchant |
| ❯ merchant_defined_uid | A string value that can be set on the sub_merchant to help identify the sub_merchant in systems external to spreedly. |
| ❯ merchant_data | An array of objects to store more information about the merchant |
| ❯❯ card_network | The merchant data fields can be different depending on the card network. So, this field is to identify the network associated with the other fields in a merchant_data object. |
| ❯❯ aquirer_merchant_id | The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ acquirer_bin | The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ business_id | The merchant’s business, company, or service identifier specific to the card-network |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯❯ merchant_data_id | Spreedly generated id for each merchant_data element |
| ❯ address | The address associated with the merchant |
| ❯❯ address1 | The first line of the merchant’s address |
| ❯❯ address2 | The second line of the merchant’s address |
| ❯❯ city | The city of the merchant’s address |
| ❯❯ state | The state of the merchant’s address |
| ❯❯ zip | The zip code of the merchant’s address |
| ❯❯ country | The Country Code in ISO 3166-1 numeric format of the merchant’s address |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
| ❯ created_at | The datetime that the sub_merchant was first created |
| ❯ updated_at | The datetime that the sub_merchant was last updated |
Update sub-merchant
PUT /v1/sub_merchants/DnVbZVjZWNBL2yvsh3SSNEMaUqS.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"sub_merchant": {
"name": "Updated submerchant name",
"merchant_email": "new@email.com"
}
}
<sub_merchant>
<name>Updated submerchant name</name>
<merchant_email>new@email.com</merchant_email>
</sub_merchant>
HTTPS/1.1 200 OK
{
"sub_merchant": {
"token": "<token>",
"name": "Updated submerchant name",
"environment_key": "<environment_key>",
"organization_key": "<organization_key>",
"merchant_url": "www.submerchanturl.com",
"merchant_email": "new@email.com",
"ein": "12-3456789",
"merchant_defined_uid": "abcd1234",
"merchant_data": [
{
"card_network": "visa",
"acquirer_merchant_id": "sub-merchant mid",
"mcc": "5978",
"acquirer_bin": "4444444444",
"business_id": "7654321",
"merchant_data_id": "0887fd7b-729a-49d3-8232-4294a262a33e"
}
],
"address": {
"address1": "100 Main Street",
"city": "Funk",
"state": "NE",
"zip": "68940",
"country": "US"
},
"metadata": null,
"created_at": "2022-08-05T17:52:28Z",
"updated_at": "2022-08-08T15:05:51Z"
}
}
<sub_merchant>
<token>{token}</token>
<name>Updated submerchant name</name>
<environment_key>{environment_key}</environment_key>
<organization_key>{organization_key}</organization_key>
<merchant_url>www.submerchanturl.com</merchant_url>
<merchant_email>new@email.com</merchant_email>
<ein>12-3456789</ein>
<merchant_defined_uid>abcd1234</merchant_defined_uid>
<address>
<address1>100 Main Street</address1>
<city>Funk</city>
<state>NE</state>
<zip>68940</zip>
<country>US</country>
</address>
<metadata nil="true"></metadata>
<created_at type="dateTime">2022-08-05T17:52:28Z</created_at>
<updated_at type="dateTime">2022-08-08T15:05:51Z</updated_at>
<merchant_data type="array">
<merchant_datum>
<merchant_data_id>0887fd7b-729a-49d3-8232-4294a262a33e</merchant_data_id>
<card_network>visa</card_network>
<acquirer_merchant_id>sub-merchant mid</acquirer_merchant_id>
<mcc>5978</mcc>
<acquirer_bin>4444444444</acquirer_bin>
<business_id>7654321</business_id>
</merchant_datum>
</merchant_data>
</sub_merchant>
Update the sub-merchant with the given key.
URL Parameters
| Parameter | Description |
|---|---|
| sub_merchant_key required |
The key of the sub-merchant to execute against |
| format required |
One of json or xml |
Note: When updating merchant_data items, a new item will be added to the merchant_data list unless it matches an existing item. If it matches an existing item it will be ignored.
Request Body
| Element | Description |
|---|---|
| sub_merchant | Root element |
| ❯ name | The human readable name of the sub_merchant |
| ❯ merchant_url | The merchant’s website url. |
| ❯ merchant_email | The email address associated with the merchant |
| ❯ ein | The employer identification number associated with the merchant |
| ❯ merchant_defined_uid | A string value that can be set on the sub_merchant to help identify the sub_merchant in systems external to Spreedly. |
| ❯ merchant_data | An array of objects to store more information about the merchant |
| ❯❯ card_network | The merchant data fields can be different depending on the card network. So, this field is to identify the network associated with the other fields in a merchant_data object. |
| ❯❯ acquirer_merchant_id required only if merchant_data present |
The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ acquirer_bin | The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ business_id | The merchant’s business, company, or service identifier specific to the card-network |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯ address | The address associated with the merchant |
| ❯❯ address1 | The first line of the merchant’s address |
| ❯❯ address2 | The second line of the merchant’s address |
| ❯❯ city | The city of the merchant’s address |
| ❯❯ state | The state of the merchant’s address |
| ❯❯ zip | The zip code of the merchant’s address |
| ❯❯ country | The Country Code in ISO 3166-1 numeric format of the merchant’s address |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| sub_merchant | Root element |
| ❯ token | The token identifying the sub_merchant at Spreedly |
| ❯ name | The human readable name of the sub_merchant |
| ❯ organization_key | The organization that the sub_merchant belongs to |
| ❯ environment_key | The environment that the sub_merchant is associated with |
| ❯ merchant_url | The merchant’s website url. |
| ❯ merchant_email | The email address associated with the merchant |
| ❯ ein | The employer identification number associated with the merchant |
| ❯ merchant_defined_uid | A string value that can be set on the sub_merchant to help identify the sub_merchant in systems external to spreedly. |
| ❯ merchant_data | An array of objects to store more information about the merchant |
| ❯❯ card_network | The merchant data fields can be different depending on the card network. So, this field is to identify the network associated with the other fields in a merchant_data object. |
| ❯❯ aquirer_merchant_id | The MID is a unique code that ensures the funds make it from the cardholder’s bank account to your bank account when a transaction is processed. It is passed with other transaction information and is used to help with transaction reconciliation. You receive a MID when you open a merchant account with an acquiring bank. A merchant can have multiple MIDs based on the different sales channels they have. |
| ❯❯ acquirer_bin | The Acquirer Bank Identification Number (BIN) is the first four to six digits of a card number that is used to identify the bank account associated with a card network. The BIN is used to submit authorization requests and ensure that payments are routed to the correct institution. |
| ❯❯ business_id | The merchant’s business, company, or service identifier specific to the card-network |
| ❯❯ mcc | The MCC is a 4-digit code that classifies the type of goods or services that the business sells. Depending on its various lines of business, a merchant could have multiple MCCs. It is mandatory and usually used during the ACS risk analysis (not to be displayed anywhere). Certain MCCs are deemed riskier than others by the issuer, and thus tend to require a stronger challenge during the authentication. |
| ❯❯ merchant_data_id | Spreedly generated id for each merchant_data element |
| ❯ address | The address associated with the merchant |
| ❯❯ address1 | The first line of the merchant’s address |
| ❯❯ address2 | The second line of the merchant’s address |
| ❯❯ city | The city of the merchant’s address |
| ❯❯ state | The state of the merchant’s address |
| ❯❯ zip | The zip code of the merchant’s address |
| ❯❯ country | The Country Code in ISO 3166-1 numeric format of the merchant’s address |
| ❯ metadata | metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types |
| ❯ created_at | The datetime that the sub_merchant was first created |
| ❯ updated_at | The datetime that the sub_merchant was last updated |
Receiver Variables
Given the following template…
{
"order_id": 12309,
"card": "{{ credit_card_number }}",
"cvv": "{{ credit_card_verification_value }}"
}
the delivery output will be:
{
"order_id": 12309,
"card": "4111111111111111",
"cvv": "123"
}
Receiver variables, available in the deliver and export elements, are referenced using the template syntax and are scoped to the payment method specified in the payment_method_token request element.
Example:
My credit token is: {{credit_card_token}}
Note: By default template tags will HTML escape all values. If you have special characters in your variable such as & > <, wrap the variable with triple curly braces to use the unescaped value:
Unescaped values: {{{#variable_name}}}& < >{{{/variable_name}}}
The list of available variables include:
Credit cards
For credit card (which includes Apple Pay and Google Pay) payment methods:
| Variable | Description |
|---|---|
| credit_card_token | The Spreedly payment method token |
| credit_card_number | The full credit card number of the payment method |
| credit_card_verification_value | The CVV of the credit card |
| credit_card_first_name | The card holder’s first name |
| credit_card_last_name | The card holder’s last name |
| credit_card_month | The numerical month of the credit card’s expiration date (e.g. 4 for April) |
| credit_card_year | The four digit year of the credit card’s expiration date (e.g. 2015) |
| credit_card_expiration_date | The credit card’s expiration date (e.g. 2020-04-01) |
| credit_card_created_at | The credit card’s created_at date (e.g. 2016-07-13 14:14:03 UTC) |
| credit_card_updated_at | The credit card’s updated_at date (e.g. 2016-07-13 14:14:03 UTC) |
| credit_card_type | The type, or brand, of the card. Please see the card_type_mapping function below for more detail. |
| credit_card_email | The card holder’s email address |
| credit_card_address1 | The card holder’s billing address line 1 |
| credit_card_address2 | The card holder’s billing address line 2 |
| credit_card_city | The card holder’s billing city |
| credit_card_state | The card holder’s billing state |
| credit_card_zip | The card holder’s billing zip |
| credit_card_country | The card holder’s billing country |
| credit_card_phone_number | The card holder’s phone number |
| last_four_digits | The last 4 digits of the credit card number |
| first_six_digits | The firs 6 digits of the credit card number |
| issuer_identification_number | The first 6 or 8 digits of the credit card number that identify the issuing bank |
Apple Pay
For Apple Pay payment methods (which also include credit_card_ variables above):
| Variable | Description |
|---|---|
| apple_pay_cryptogram | The online payment cryptogram associated with this Apple Pay payment method |
| apple_pay_currency_code | The numerical currency code, e.g., “840” |
| apple_pay_eci_indicator | The Apple Pay eci indicator |
| apple_pay_exp_date | the Apple Pay formatted expiration date as “yymmdd”. You can also access the apple pay expiration date values via credit_card_month and credit_card_year. |
| apple_pay_transaction_amount | The original Apple Pay transaction amount |
| apple_pay_transaction_id | The original Apple Pay transaction id |
Google Pay
For Google Pay payment methods (which also include credit_card_ variables above):
| Variable | Description |
|---|---|
| google_pay_cryptogram | The online payment cryptogram associated with this Google Pay payment method |
| google_pay_transaction_id | The original Google Pay transaction id |
| google_pay_eci_indicator | The Google Pay eci indicator |
| google_pay_auth_mode | The Google Pay auth mode |
| google_pay_month | The Google Pay expiration month |
| google_pay_year | The Google Pay expiration year |
Bank account
For bank account (ACH) payment methods:
| Variable | Description |
|---|---|
| bank_account_first_name | The bank account owners first name |
| bank_account_holder_type | The bank account holder type (e.g. personal or business) |
| bank_account_last_name | The bank account owners last name |
| bank_account_number | The bank account number |
| bank_account_routing_number | The bank account routing number |
| bank_account_type | The bank account type (e.g. checking or savings) |
Paypal
For Paypal payment methods:
| Variable | Description |
|---|---|
| paypal_email | The email address associated with the payment method |
Credentials
Additionally, any credential values set when provisioning the receiver, will be exposed as variables. So if user and password were set as receiver credentials, they would available as {{ user }} and {{ password }} in the delivery values.
Miscellanous
The following non payment method variables are also available:
| Variable | Description |
|---|---|
| utc_timestamp | The timestamp of the current time in iso8601 format, e.g., 2024-11-07T20:38:59Z |
| binary_security_token | The binary security token value for a receiver requiring WS-Security integration. |
Receiver Functions
Receiver functions, available in the deliver and export elements, are invoked using the template syntax and operate on the contents contained within the {{#name}} and {{/name}} container tags. The list of available functions include:
# and ^ (conditional rendering)
Given the following template…
{
"order_id": 12309,
"card": "{{ credit_card_number }}",
"cvv": {{#credit_card_verification_value}}"{{credit_card_verification_value}}"{{/credit_card_verification_value}}{{^credit_card_verification_value}}null{{/credit_card_verification_value}}
}
If
credit_card_verification_valuehas a non-empty value, the delivery output will be:
{
"order_id": 12309,
"card": "4111111111111111",
"cvv": "123"
}
<order_id>12309</order_id>
<card>4111111111111111</card>
<cvv>123</cvv>
Else if
credit_card_verification_valueis blank, the delivery output will be:
{
"order_id": 12309,
"card": "4111111111111111",
"cvv": null
}
<order_id>12309</order_id>
<card>4111111111111111</card>
<cvv>null</cvv>
The section operator # and the inverted section operator ^ can be used in conjunction to render a value if it is present and specify an alternative if the value is empty, false, or not present.
This can be useful for specifying a default like null in cases where an empty value would otherwise render a blank field or an empty string.
aes
{{#base64}}{{#aes}}192,CBC,[23, 12, 1, 105, 1, 1, 11, 18, 9, 39, 191, 125, 20, 132, 2, 16],mysecretkeyXXXXXXXXXXXXX,{{ credit_card_number }}{{/aes}}{{/base64}}
EXGKeEUL3EyxlMNJcjNK3M4uONJ4VhRwY7Yg/hP4phI=
Encrypt contents using the Advanced Encryption Standard (AES) symmetric encryption algorithm.
{{#aes}}key-length in bits,mode,initialization vector as unsigned byte array,encryption key{{/aes}}
The encryption mode can be one of cbc, ccm, cfb, ctr, ecb, gcm, ofb, xts.
Because the raw output is in binary form you will often use the aes function embedded within another encoding function, such as base64, to produce web-safe output.
alpha3
{{#alpha3}}{{credit_card_country}}{{/alpha3}}
USA
Takes either the alpha2 country code or the full country string and returns the alpha3 country code.
apple_pay?
{{#apple_pay?}}I'm an Apple Pay payment method{{/apple_pay?}}
I'm an Apple Pay payment method
If the payment method is an Apple Pay payment method, evaluates to true. You can use this to conditionally evaluate a section.
google_pay?
{{#google_pay?}}I'm a Google Pay payment method{{/google_pay?}}
I'm a Google Pay payment method
If the payment method is a Google Pay payment method, evaluates to true. You can use this to conditionally evaluate a section.
bank_account?
{{#bank_account?}}I'm a bank account payment method{{/bank_account?}}
I'm a bank acount payment method
If the payment method is a bank account payment method, evaluates to true. You can use this to conditionally evaluate a section.
base64
Authorization: Basic {{#base64}}{{ user }}:{{ password }}{{/base64}}
Authorization: Basic dXNlcjpQYSQkd2VyZA==
Base 64 encode contents.
A common use of base 64 encoding is in HTTP Basic authentication, which base 64 encodes user:password credentials into the Authorization header.
{{#base64}}contents to encode{{/base64}}
binary_security_token
{{#binary_security_token}}{{#certificate}}M6A4yufjd04Ey4u6cCIzxdoUMz5{{/certificate}}{{/binary_security_token}}
For receivers that require an X.509 certificate (for example, Mastercard), binary_security_token will insert the Base64-encoded certificate.
{{#binary_security_token}}{{#certificate}}your certificate token{{/certificate}}{{/binary_security_token}}
bytes_hex
{{#bytes_hex}}61626378797a{{/bytes_hex}}
abcxyz
Takes a hex string and turns it into raw bytes. This function is rarely useful by itself, but can be helpful when paired with functions such as aes.
{{#bytes_hex}}hexadecimal string to decode{{/bytes_hex}}
certificate
{{#certificate}}M6A4yufjd04Ey4u6cCIzxdoUMz5{{/certificate}}
-----BEGIN CERTIFICATE-----
MIIDMDCCAhgCCQCJjV5tUn0DNTANBgkqhkiG9w0BAQsFADBaMTMwMQYDVQQDDCpN
eUFwcCBYTUwgU2lnbmF0dXJlIFByb2R1Y3Rpb24gQ2VydGlmaWNhdGUxIzAhBgkq
hkiG9w0BCQEWFHNlY3VyaXR5QHlvdXJvcmcuY29tMB4XDTE5MDQwMjE4MjIzMFoX
DTIwMDQwMTE4MjIzMFowWjEzMDEGA1UEAwwqTXlBcHAgWE1MIFNpZ25hdHVyZSBQ
cm9kdWN0aW9uIENlcnRpZmljYXRlMSMwIQYJKoZIhvcNAQkBFhRzZWN1cml0eUB5
b3Vyb3JnLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMldbCSv
WjRO+jOB9pObeRzVU3QqpsRTH9Rw7n3LniuPbdbI98BvabGVzwWp+nCyRMu21aNk
CJfzUA8Ggubw4CIiSiM/isMXhdavtIrdnLrcVEY1mOMnMbP1rjiXsEhyDC/hmYc4
V9JyfMQoiSs8n8aAXZQE65TCO9BnIKpr+V4ew/gkeucpyLlPCd2DEZ+24aI3Lnli
Q/ABIdNSlQX44n56NX9lui4+nrsb8ImqWjE2YqB3vLh+IHjlcOViLiN7i7EeUTbi
0/6vxbdEiMLnr36eqHQpAAuvQCL7bTxH6hnKjZ/hdHy0Z59gHfmEbIqbjmHn1gT5
sPkhYpMb5JYiq38CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAGNjf8tNsQ/mvQNk4
3b4knwlCIT6elhiofeKXoV9224C5ZcM1bw0hRfeEIXG5fs8ZEwlLGAS+bNgCctmW
NcuqxEreR4TiV07WT/18m1go+34IygGxlxgntLQOZQyX6mjVyZjgOjefweA8OFyG
s+xqgVuR9G7Zu8KFW0MaCj7QZBl1h4FfA3Hz25R1WC2qcbY04Db3EkLYPU4hBEzX
HXkAyW5LWRk4pzxew9CRQ+uHyumPyi2O6Yv9avI9QA5PkuRoH0xgQ87n3AXgQ08p
HDoiNxcDFhfL13lspowI40bsOWfGm2vvTrV42PvobHB2Hwb3a77mM2Z6bCvdN32R
jn30kQ==
-----END CERTIFICATE-----
For receivers that have SOAP security requirements and need an X.509 certificate to generate a WS-Security Binary Security Token, certificate will insert the PEM-encoded certificate from the certificate securely stored at Spreedly.
{{#certificate}}your certificate token{{/certificate}}
Requires an encryption certificate to be stored using the certificates API. Used in conjunction with binary_security_token.
card_type_mapping
{{#card_type_mapping}}visa:Visa,master:MasterCard,american_express:American Express{{/card_type_mapping}}
Visa
Output a custom card brand. You can always retrieve the type, or brand, of the payment method using the credit_card_type variable which outputs one of the following values. To output a value different than the default, use the card_type_mapping to translate it to the format you need.
{{#card_type_mapping}}brand:output,brand:output{{/card_type_mapping}}
Any card types whose value is not mapped in the function body will have the default credit_card_type value used. E.g., if Diners Club card type is not specified the default diners_club would be output.
credit_card?
{{#credit_card?}}I'm a credit card payment method{{/credit_card?}}
I'm a credit card payment method
If the payment method is a credit card payment method, evaluates to true. You can use this to conditionally evaluate a section.
digest
{{#base64}}{{#digest}}sha512,{{ credit_card_number }}{{/digest}}{{/base64}}
MkwVgWyhqy7FWHGIKn/jvUsUbD6BGaT...n6NvY=
Digests contents using the specified digest algorithm.
{{#digest}}digest-algorithm,contents to digest{{/digest}}
The digest algorithm can be one of sha512 or sha256.
Because the raw output is in binary form you will often use the digest function embedded within another encoding function, such as base64, to produce web-safe output.
format_date
{{#format_date}}%m%y,{{credit_card_expiration_date}}{{/format_date}}
0120
Parse a date value to a specific string format.
{{#format_date}}format-specifier,date-field{{/format_date}}
The format specifier syntax is based on the posix date format. Common format syntax includes:
%Y: 4-digit year. E.g., 2020%y: 2-digit year. E.g., 20%m: 2-digit month number (zero-padded). E.g., 04%-m: month number (not padded). E.g., 4
format_text
"number": "{{#format_text}}%-20.20s,{{credit_card_number}}{{/format_text}}"
"number": "4111111111111111 "
Parse text context to a specific format. Useful when right or left padding a value to a specific width, among other scenarios.
{{#format_text}}format-specifier,text to format{{/format_text}}
The format specifier is based on posix printf. Common format syntax includes:
%20.20s: total length of 20, right justified w/ space fillers%-20.20s: total length of 20, left justified w/ space fillers
gpg
{{#gpg}}-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: IPWorks! OpenPGP v9.0
rsBNBFda3S0BCzCPTH1Td1PSUSMeaTDAagncwV18KrpuXSPXWjTgPy9SLHeoKQDt
lxWlIoisyxV1Ex2LQZnidINgNCFzMi26+SqYucm6OFv2bllr91tpk8I0+aeL/XBC
h5DUEbG9JAMyegMyzTz9PjRu4peXV/IUf2/uBJifZyv1bBaARCBXBaHvv+qfJbHx
88QNVo5J7KU8C7MD8hqLxwtqDjHgKtXHGbyscMzJn+ySTueemqhOBI3jst/z9uL2
OuSXeO0DudcLsmp6bVrh3SqpLKiZMbj2GsNcwVA/ikJiriaXOESv2RI/h1j5MjRs
sg9tyJYytuDsqz/rEOVDnqfP5/xpiTX223tjABEBAAHNJHNmaWxlMi1sYS10YXFj
LVBST0QgPG5hd2VzQHZpc2EuY29tPsLAdAQTAQIAHgUCV1oNLwMLAgIEFQoIAgUW
AQIDAAIeAQIXgAIbDwAKCRBPCXevH0QlBoxhB/4o7sG1TOZlxjv9fuK1/Bx9ZjPJ
6zCWGEAMV3li/jDmiNfJUaJOL5ZV8ffLRhgvS6bvKlpdMaRY8FXuJQThGe4T/BU4
HJIP8jPR+x4CHoUHNw1rOVitdkc9y/tWoF7aYAWqcqBBQwqjH9XbSC2XcYbULcl8
j8rVVTbXvJIdnx7u6v9OOeyc6XO7AupV7zjQHE6bdDPnmhyM9Yf+1OkDxuGNywsv
0WP8iB847/ZPmaENvOofIsrbncbztgZu1V2fOJM6JRp0EbctSxP44Mk1K8AKcmx2
MFqkPdKpeZh2bO269Td8fMy82gx6ltzMtms2NrRL3NOWj6suLke7s8K8++JC
=Zp6G
-----END PGP PUBLIC KEY BLOCK-----,recipient@example.com,{{#payment_methods}}{{credit_card_number}}{{/payment_methods}}{{/gpg}}
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1
hQEMA50hlo9S0ThAAQf+OF7KFqdmXbCnnJrZ7xWtI33mZ7a2jQcpOTavof8LbURm
nSl/HRa9T48ExxOYNBxfIXXUjHLk9FQIUU7nH/Gomz2gGVCFQ/8C1mn5Xbfo+WTF
370QShAiG7pJT9801L1/uIpSmMKjjlcwmS2V+WY4tEONCJeqE0yOMqqfc7Pvn0YG
-----END PGP MESSAGE-----
For some SFTP endpoints (batch export), the receiver requires the uploaded file to be encrypted using GnuPG and their public key.
{{#gpg}}full pem,recipient identity,file template to encrypt{{/gpg}}
The gpg function takes the public key in PEM form as the first argument, the target identity as the second (email address of the recipient), and the content to encrypt as the third. The third argument will be your entire templated export which can include other receiver functions are variables.
hex_bytes
{{#hex_bytes}}-,string to encode{{/hex_bytes}}
FE-4C-65-6A-0F-35-0F
Takes a byte string and turns it into a hex string.
{{#hex_bytes}}delimiter,byte string to encode{{/hex_bytes}}
hex_digest
{{#hex_digest}}sha512,{{ credit_card_number }}{{/hex_digest}}
0e422979315a8b64fb9cbbafc6d2c3c0589ab8b58ede93e73b1acc5d027dffaf
Digests contents using the specified digest algorithm, printing out the hexadecimal encoding.
{{#hex_digest}}digest-algorithm,contents to digest{{/hex_digest}}
The digest algorithm can be one of sha512 or sha256.
hmac
{{#hmac}}SHA256,key,{{ credit_card_number }}{{/hmac}}
d7deb2f89396a762e0f485ff629bed80118728d1ef5d5744f870a99001a1437d
Computes the HMAC of a given payload. The payload is returned as a hexadecimal string. The digest algorithm can be any of SHA1, SHA256, or SHA512.
{{#hmac}}digest algorithm,secret key,payload whose digest is desired{{/hmac}}
kount_khash
{{#kount_khash}}{{ credit_card_number }}{{/kount_khash}}
411111WMS5YA6FUZA1KC
Generate a Kount KHash payment encoding for use with Kount fraud prevention service for credit cards.
last
{{#last}}4,{{ credit_card_number }}{{/last}}
1111
Get the last characters of a value.
This function cannot be used with the following variables credit_card_verification_value, apple_pay_cryptogram, and google_pay_cryptogram.
The last function can be used for credit_card_number and account_number if the length passed is less than or equal to 4.
Using the last function inappropriately with one of the sensitive variables will result in an error with a key of “errors.receiver_last_function” and a message of “Receiver transaction not attempted due to invalid use of last receiver function”
{{#last}}length,contents{{/last}}
lowercase
{{#lowercase}}LOWERCASE TEXT{{/lowercase}}
lowercase text
Convert a given string to lowercase.
md5
{{#md5}}{{ credit_card_number }}:{{ secret }}{{/md5}}
c7de95291d0ebb132b7ec76eee4c3eb9
Calculate the MD5 digest of the contents.
{{#md5}}value to digest{{/md5}}
payment_method_metadata
{{#payment_method_metadata}}some_key{{/payment_method_metadata}}
the value of some_key
payment_method_metadata takes a single parameter, the key of the metadata field you’d like to render the value of. For example, if you have a payment method with a metadata field of item_id and it has a value "1234", you’d use payment_method_metadata with the parameter item_id to render "1234".
payment_methods
{{#payment_methods}}{{credit_card_number}}
{{/payment_methods}}
4111111111111111
5555555555554444
Iterate over the list of submitted payment methods. For each payment method, the scope of the function body is re-bound to the payment method, meaning all receiver variables are available within this iterator.
{{#payment_methods}}content to render for each payment method{{/payment_methods}}
replace
{{#replace}}A,B,ABACABD{{/replace}}
BBBCBBD
Replaces every instance of a given pattern with a new value in the content. Neither the pattern nor replacement can themselves contain commas.
{{#replace}}pattern,replacement,content{{/replace}}
rsa
{{#base64}}{{#rsa}}-----BEGIN CERTIFICATE-----
MIIEyjCCA7KgAwIBAgIJAIWfA5mfOXNpMA0GCSqGSIb3DQEBBQUAMIGeMQswCQYD
VQQGEwJVUzEXMBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExDzANBgNVBAcTBkR1cmhh
bTEXMBUGA1UEChMOU3ByZWVkbHksIEluYy4xIjAgBgNVBAMTGVNwcmVlZGx5IFRl
c3QgQ2VydGlmaWNhdGUxKDAmBgkqhkiG9w0BCQEWGWludGVncmF0aW9uc0BzcHJl
ZWRseS5jb20wHhcNMTUwMjExMTkxNTU4WhcNNDIwNjI5MTkxNTU4WjCBnjELMAkG
A1UEBhMCVVMxFzAVBgNVBAgTDk5vcnRoIENhcm9saW5hMQ8wDQYDVQQHEwZEdXJo
YW0xFzAVBgNVBAoTDlNwcmVlZGx5LCBJbmMuMSIwIAYDVQQDExlTcHJlZWRseSBU
ZXN0IENlcnRpZmljYXRlMSgwJgYJKoZIhvcNAQkBFhlpbnRlZ3JhdGlvbnNAc3By
ZWVkbHkuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApdxYbGMc
1A2ZBipEuxIZhhonLjhENg2foEk2w5dUjBzqbzzDeK8+zMCFCJOrq3jnjBSkgtPa
KRrCR/bXdyrvt+lmm+OVrgNyLQgInFR2frdYtlpWbuC8z5DqP3KOMhir3lpwpoBx
RM6JmK1uld03HAG4q67hYLjLDqlqXM87JnhnXytVvSUv7dDazcRXefrZox2xERVz
2F4e2QXQckvNDZEL44Hzp52F25SsECtVr+F11T5PrM5y5fyP4/QJzPAqj3dhXMKg
cVDb2Rv/el98s8p2wkrOCf/rVfj+xfREEYh2T3D9jyZZWcAjvs8e363QxhMtgOg1
/5/8mjfqYT7RUwIDAQABo4IBBzCCAQMwHQYDVR0OBBYEFAv+9ULX/Sv8z63mRs/w
rnOcMgbXMIHTBgNVHSMEgcswgciAFAv+9ULX/Sv8z63mRs/wrnOcMgbXoYGkpIGh
MIGeMQswCQYDVQQGEwJVUzEXMBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExDzANBgNV
BAcTBkR1cmhhbTEXMBUGA1UEChMOU3ByZWVkbHksIEluYy4xIjAgBgNVBAMTGVNw
cmVlZGx5IFRlc3QgQ2VydGlmaWNhdGUxKDAmBgkqhkiG9w0BCQEWGWludGVncmF0
aW9uc0BzcHJlZWRseS5jb22CCQCFnwOZnzlzaTAMBgNVHRMEBTADAQH/MA0GCSqG
SIb3DQEBBQUAA4IBAQALuWTjcKmzgGZrYkHrstqIzt1jxMBSknFxn94hm7O1Ip97
2kWyTxrvhMiyJMYiwH2oyf1iD3zMh4/kLDXJrHNA00wK9ptVGu85cxH3VBJgvIY7
nykV5mDhGosxQlZvgrUDVe50+x4sgJP6zJpQepdYPW5qfyEp9HVkddNKhCEPIGW6
C3X41C4gyTACwZ1JVldC9rAZxs38e9TAD+Ogz5pxgHokhlUiypL+P3Lf6wHj3hzw
QbOiY+x+MEFVD55kKf7BB6CCJPaEN/yYovDqcpVCK9hnK04Iyw//+eCQry2U73Ns
ASkL7Z69EL+OabkrfQu4AM9eA+h1ZHwGXmFFL1Gn
-----END CERTIFICATE-----,oaep,{{ credit_card_number }}{{/rsa}}{{/base64}}
G9RUciV1y7JUGEJjwPqvRvn...GP5NK/OSSSoObfLQ==
Encrypts contents using RSA public key cryptography.
{{#rsa}}certificate-pem,padding-scheme,contents to encrypt{{/rsa}}
The certificate value must be in PEM format. The currently available padding schemes include: pkcs1 or oaep.
Because the raw output is in binary form you will often use the rsa function embedded within another encoding function, such as base64, to produce web-safe output.
rsa_sign
{{#rsa_sign}}sha512,{{ credit_card_number }}{{/rsa_sign}}
MkwVgWyhqy7FWHGIKn/jvUsUbD6BGaT...n6NvY=
Signs (and base64 encodes) contents using the private key configured for the receiver. Requires a receiver pre-configured with an encryption certificate.
{{#rsa_sign}}digest-algorithm,contents to sign{{/rsa_sign}}
The digest algorithm can be one of sha512 or sha256.
triple_des
{{#hex_bytes}}-,{{#triple_des}}CBC,[15, 66, 13, 102, 1, 1, 11, 18],testKeyXXXXXXXXXXXXXXXXX,1234123412341234{{/triple_des}}{{/hex_bytes}}
BB-99-AA-68-3A-49-92-B5-BE-D6-91-D7-B0-1B-78-22-07-9B-DA-04-54-46-1F-9D
Encrypt contents using the Triple DES (3DES) symmetric encryption algorithm.
{{#triple_des}}mode,initialization vector as byte array,encryption key,data{{/triple_des}}
The encryption mode can be one of CBC, CFB, OFB, CTR.
Because the raw output is in binary form you will often use the triple_des function embedded within another encoding function, such as base64, to produce web-safe output.
Note that 3DES encryption is not generally acceptable for use in a PCI-compliant context, as 3DES encryption can be broken in a trivial amount of time on normal desktop computers and cell phones. You should instead use alternative mechanisms, such as AES encryption, in most contexts.
truncate
{{#truncate}}6,{{ credit_card_number }}{{/truncate}}
411111
Truncate a value to a given size.
This function cannot be used to truncate the following variables account_number, credit_card_verification_value, apple_pay_cryptogram, or google_pay_cryptogram.
The truncate function can be used for credit_card_number if the length passed is less than or equal to 6.
Using the truncate function inappropriately with one of the sensitive variables will result in an error with a key of “errors.receiver_truncate_function” and a message of “Receiver transaction not attempted due to invalid use of truncate receiver function”
{{#truncate}}length,contents{{/truncate}}
uppercase
{{#uppercase}}uppercase string{{/uppercase}}
UPPERCASE STRING
Convert a string to uppercase.
uri_encode
{{#uri_encode}}http://example.com?testing=t{{/uri_encode}}
http%3A%2F%2Fexample.com%3Ftesting%3Dt
URI-encode a string.
utc_timestamp
{{#utc_timestamp}}{{/utc_timestamp}}
2017-01-01T12:00:01Z
Inserts an ISO 8601 formatted timestamp at the time of export.
xml_dsig
{{#xml_dsig}}M6A4yufjd04Ey4u6cCIzxdoUMz5,<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope>...</soapenv:Envelope>{{/xml_dsig}}
{{#xml_dsig}}-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAyV1sJK9aNE76M4H2k5t5HNVTdCqmxFMf1HDufcueK49t1sj3
wG9psZXPBan6cLJEy7bVo2QIl/NQDwaC5vDgIiJKIz+KwxeF1q+0it2cutxURjWY
4ycxs/WuOJewSHIML+GZhzhX0nJ8xCiJKzyfxoBdlATrlMI70Gcgqmv5Xh7D+CR6
5ynIuU8J3YMRn7bhojcueWJD8AEh01KVBfjifno1f2W6Lj6euxvwiapaMTZioHe8
uH4geOVw5WIuI3uLsR5RNuLT/q/Ft0SIwuevfp6odCkAC69AIvttPEfqGcqNn+F0
fLRnn2Ad+YRsipuOYefWBPmw+SFikxvkliKrfwIDAQABAoIBAQCAUYNPoVrHSKjS
V/hsub+lKyAiP+fD5gC7nTetfCsQMTdajviqbZUZ8JBbWKVaWY/TjXB4zY9YXVng
KVMTnd4GgnliGuTvS7cjRxazA2QUA8HEd/U0k85tkpryP1+72sl/XbE7ZSE533E4
g2hd4CUlFroLUFNbmacKOB2t3F6tpaXZD3TXGd2QIWEdRVbBHcbH5ZLhOVlvyJ5k
+gHXvpdVsZnmC8eZPPs/JL3B0SwJop8Ln+DKkg6P4s+oq9dkR0OwuhuE+iWV8evF
LFb0j87kJV8JsHMvk3qbbunWHisQr23U4Vl/k6rjkodryrzDrwQ3czzR3nlKN/Kl
VROR8TMBAoGBAOmi434+RbZQP9PdVEa+pEh2IA81L3og6+TqemL4sZtqlCEfrOZD
FsSH6CEU13SMn7l+riYCzBYSdvPDAynhJp+u0REUQFPJAMcgefxw2mfJwFrtn9Ap
JWaAPhcMeK8l/5rdZxnjECDRAkW+5SdtYj9x6rjgsmJ89DFdd5EW1JL/AoGBANyj
vpNSRBdy+lM62T0DiAJ6gc0HpYQpNzIydIT9bh8zkmwU5z0pVtczpmIzdK0lPlHO
ERWgBXXsfRfEupVoFND9H5A7tTMQtJF4rLg3gUpa2alTUXSWfm9uS7TWVRYR7hsV
/ui7oW3zIXdD8dRHozITSzM27gfiMy6Q3I/SIGeBAoGAf0lgObJBlq8n5wxpUtWg
eV3p338xa48uFZxtqygk0zCAnX89WoHokJAeto89RuEqUAwlYs4ZVFkg93MicRma
SlsayfxHg545z0LxUshFJVB0fNWDQQx5tNtfeH0x7vJ7zGqdNixP6CEW5Nq4y/87
DKfKoojAhwnenFp4vtI6ZA8CgYBqTvcvEo8+YSbd3Vf4fvAUiaRq/okwgY9Xv1nH
Djj2Dao6K2QzYuy1qew8GqDYID7Dua8fpUecRwMK5b4k6M5G1/9SRoKLBTyLbwKB
jDTed6GyZTO1IiHvXMxbaH38sUzxfgqhZm5khKYWSgWGC7JFGWi9V3UfFU0l3aR4
I317gQKBgQCxWrKZlfq/iWcvBqB8Ep4wiJPXZXjl/Dvic/2pCC69MMimtDTHQ8o8
gp7c3Fp+RDO8U5wgqq2amodR1RPbAdgG7rQvewnzPsaTIKSfOueY3LG4UR22tNvZ
LeaSV7WUssler/Ybk6Gj+psx8RXbL+ZcYPoeL7mb6kUoWFfzcmpIjA==
-----END RSA PRIVATE KEY-----,<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope>...</soapenv:Envelope>{{/xml_dsig}}
Generate the WS-Security XML digital signature for a given SOAP message. Requires an encryption certificate with private key to be stored using the certificates API OR a PEM-encoded private key.
{{#xml_dsig}}your certificate token OR private key pem,full XML body{{/xml_dsig}}
The private key value must be a PEM formated RSA private key.
Field-Level Encryption
POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"payment_method": {
"credit_card": {
"first_name": "Joe",
"last_name": "Jones",
"number": "PKlniC9+6uFMp8D7CN7DqYEtLSPGFvcnTB7jgaZx2NkxakyTzee0S1zJPuaxHoHGgD4nVWKyFJmzO5CEhQoPNFHgQJ6YnDQLLfHnnN+GXKPs38qiyoXJQdUYldGm+WoKKp3Shui6KL2T6SoUOy3GRbMMQEy8DCK3P78YS55jOguonInHA2+bmKGZE/45sWY00rIMdUc8MY4rwkEp4cs5eXPwxAhoaQU1LEfhGjrYqS64JoXEuA1sK1Hm22bbO15AGt/NtQ/LlwAhyfrz6t8Qa9qvYOSOfcGDvGPq73mw/13mEA+Ht5gnXD41aYUBgxWF4YUE/ovzH+HNvyXOta0jfg==",
"verification_value": "iGKnnyYYLXNWmZgTERFLR5mSno4u1pum12jACuo2KC55bmB9yk4+C+WuUP6TVpJOimjgFMsTh2XOguXG3Ec7RRoWeIsQgQQTviAmydGmeDwNu08KNGQRs9CIqktvzenUOoOzSDb6nSMF7PeznTs2CDt7ElM6ntZHFO8NRfijSAI9kFWiPYb6ZPfTYfUZIVkrDHTwORgjQNa9LtcUxgTgprKY3zanmNUpJ5be9IiQngOes/1yNdcCK0TG0fzju1AznoPN4LDPi4HX8Z4H/7i9kedvENZWU4CQXbCvWU4IBjClToCSbGME2wnwPx9+eqoEpoyHLJFPxqWrRIaYpEPH4w==",
"month": "3",
"year": "2029",
"address1": "33 Lane Road",
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US"
},
"email": "joey@example.com",
"metadata": "csWWNHl9cYgNO6WhNvuch+2jXoe0O7nrZN/Zbf4cKvhvkNUTp+Hl6MkvPiXpXImRUw5sMV6niCMra85bsURByllUWSpd+BfltOrOpk4Lt9am6yrMyMotQ8bkIbGmfTvKepL2S4bWjV9Ky4gDq4FKdKQCsX1DrHlIADbgBUiJvdRNC1Z8wBNWcImUCju359INp1qzzOt8ZjAYqL9xIqzGS2DNM7f+JxuDyMEN8uAdhEL4Dvvs2kSMHX8ho7xtYCP3kYkSopF7vaxOucEqgPRfbXAdsSL9Qkp3ohS4biCdIqbwfuQCJY9la0psHalYebQ6NWN2e60W6N1IrtShRHWXHg==",
"encryption_certificate_token": "Rkx3hmgN4QRuq8ZUunHdGpSniCg",
"encrypted_fields": "number, verification_value, metadata"
}
}
<payment_method>
<credit_card>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<number>PKlniC9+6uFMp8D7CN7DqYEtLSPGFvcnTB7jgaZx2NkxakyTzee0S1zJPuaxHoHGgD4nVWKyFJmzO5CEhQoPNFHgQJ6YnDQLLfHnnN+GXKPs38qiyoXJQdUYldGm+WoKKp3Shui6KL2T6SoUOy3GRbMMQEy8DCK3P78YS55jOguonInHA2+bmKGZE/45sWY00rIMdUc8MY4rwkEp4cs5eXPwxAhoaQU1LEfhGjrYqS64JoXEuA1sK1Hm22bbO15AGt/NtQ/LlwAhyfrz6t8Qa9qvYOSOfcGDvGPq73mw/13mEA+Ht5gnXD41aYUBgxWF4YUE/ovzH+HNvyXOta0jfg==</number>
<verification_value>iGKnnyYYLXNWmZgTERFLR5mSno4u1pum12jACuo2KC55bmB9yk4+C+WuUP6TVpJOimjgFMsTh2XOguXG3Ec7RRoWeIsQgQQTviAmydGmeDwNu08KNGQRs9CIqktvzenUOoOzSDb6nSMF7PeznTs2CDt7ElM6ntZHFO8NRfijSAI9kFWiPYb6ZPfTYfUZIVkrDHTwORgjQNa9LtcUxgTgprKY3zanmNUpJ5be9IiQngOes/1yNdcCK0TG0fzju1AznoPN4LDPi4HX8Z4H/7i9kedvENZWU4CQXbCvWU4IBjClToCSbGME2wnwPx9+eqoEpoyHLJFPxqWrRIaYpEPH4w==</verification_value>
<month>3</month>
<year>2029</year>
<address1>33 Lane Road</address1>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
</credit_card>
<email>joey@example.com</email>
<metadata>csWWNHl9cYgNO6WhNvuch+2jXoe0O7nrZN/Zbf4cKvhvkNUTp+Hl6MkvPiXpXImRUw5sMV6niCMra85bsURByllUWSpd+BfltOrOpk4Lt9am6yrMyMotQ8bkIbGmfTvKepL2S4bWjV9Ky4gDq4FKdKQCsX1DrHlIADbgBUiJvdRNC1Z8wBNWcImUCju359INp1qzzOt8ZjAYqL9xIqzGS2DNM7f+JxuDyMEN8uAdhEL4Dvvs2kSMHX8ho7xtYCP3kYkSopF7vaxOucEqgPRfbXAdsSL9Qkp3ohS4biCdIqbwfuQCJY9la0psHalYebQ6NWN2e60W6N1IrtShRHWXHg==</metadata>
<encryption_certificate_token>Rkx3hmgN4QRuq8ZUunHdGpSniCg</encryption_certificate_token>
<encrypted_fields>number, verification_value, metadata</encrypted_fields>
</payment_method>
HTTPS/1.1 200 OK
{
"transaction": {
"token": "JcfBsU7qUy9y7DcRGJ7gq9btgX2",
"created_at": "2022-02-16T18:46:11Z",
"updated_at": "2022-02-16T18:46:11Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"encrypted_fields": "number, verification_value, metadata",
"encryption_certificate_token": "Rkx3hmgN4QRuq8ZUunHdGpSniCg",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "a26wp2B1waCkLQ334eU4g0GY1sV",
"created_at": "2022-02-16T18:46:11Z",
"updated_at": "2022-02-16T18:46:11Z",
"email": "joey@example.com",
"data": null,
"storage_state": "cached",
"test": true,
"metadata": {
"key_1": "string value",
"key_2": 123
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Joe",
"last_name": "Jones",
"month": 3,
"year": 2029,
"address1": "33 Lane Road",
"address2": null,
"city": "Wanaque",
"state": "NJ",
"zip": "31331",
"country": "US",
"phone_number": null,
"company": null,
"full_name": "Joe Jones",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
<transaction>
<token>JcfBsU7qUy9y7DcRGJ7gq9btgX2</token>
<created_at type="dateTime">2022-02-16T18:46:11Z</created_at>
<updated_at type="dateTime">2022-02-16T18:46:11Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<encrypted_fields>number, verification_value, metadata</encrypted_fields>
<encryption_certificate_token>Rkx3hmgN4QRuq8ZUunHdGpSniCg</encryption_certificate_token>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>a26wp2B1waCkLQ334eU4g0GY1sV</token>
<created_at type="dateTime">2022-02-16T18:46:11Z</created_at>
<updated_at type="dateTime">2022-02-16T18:46:11Z</updated_at>
<email>joey@example.com</email>
<data nil="true"></data>
<storage_state>cached</storage_state>
<test type="boolean">true</test>
<metadata>
<key_1>String Value</key_1>
<key_2>123</key_2>
</metadata>
<callback_url nil="true"></callback_url>
<last_four_digits>4111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Joey</first_name>
<last_name>Jones</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1>33 Lane Road</address1>
<address2 nil="true"></address2>
<city>Wanaque</city>
<state>NJ</state>
<zip>31331</zip>
<country>US</country>
<phone_number nil="true"></phone_number>
<company nil="true"></company>
<full_name>Joey Jones</full_name>
<eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
<shipping_address1 nil="true"></shipping_address1>
<shipping_address2 nil="true"></shipping_address2>
<shipping_city nil="true"></shipping_city>
<shipping_state nil="true"></shipping_state>
<shipping_zip nil="true"></shipping_zip>
<shipping_country nil="true"></shipping_country>
<shipping_phone_number nil="true"></shipping_phone_number>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value>XXX</verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Spreedly supports encrypting the payload of individual request fields on select API calls. This is currently available when adding a credit/debit card or a bank account to your Spreedly vault using the create credit card or create bank account API calls.
To use Field-Level Encryption, you must have already created or generated an RSA certificate in your authenticated Spreedly environment using the certificates endpoint. (Note that the certificate must be an RSA certificate. ECC certificates are not supported for this feature.)
Once your Spreedly environment has an RSA certificate, you will use the public key associated with that certificate to encrypt your values. The resulting encrypted values must then be base64-encoded prior to being included in your request.
If you are encrypting any rich object fields, like metadata, you should encrypt the entire JSON object as if it were one value, versus encrypting each element of the object individually.
Request Body
| Element | Description |
|---|---|
| transaction | Root request element |
| ❯ encryption_certificate_token required |
The token of the certificate used for encryption |
| ❯ encrypted_fields required |
A list of all request fields that are encrypted, in the format “field_1, field_2” or “[field_1, field_2]” |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| transaction | Root element |
| ❯ encryption_certificate_token | The certificate token sent in the request |
| ❯ encrypted_fields | The list of encrypted fields sent in the request |
Account Updater
{
"transaction":
{
"token": "S6cl5f11LqdVLe9m1TtQGMSMUuz",
"created_at": "2019-02-13T13:40:43Z",
"updated_at": "2019-02-13T13:42:48Z",
"succeeded": true,
"transaction_type": "ReplacePaymentMethod",
"state": "succeeded",
"account_key": "2H2HmVvjh171NvjCzr37D7jWG6c",
"environment_key": "DDB58wpfgxHA1qD7p0LkqCLBnZw",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "EjpBzUVNHWnF1Y0MNaefuNpXwyR",
"created_at": "2019-02-13T13:27:53Z",
"updated_at": "2019-02-13T13:40:43Z",
"email": "mm@example.com",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": "https://7fba2acd.ngrok.io",
"last_four_digits": "0003",
"first_six_digits": "511201",
"card_type": "master",
"first_name": "Mighty",
"last_name": "Mouse",
"month": 1,
"year": 2050,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Mighty Mouse",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [],
"fingerprint": "84fd610e28258201fffea68dc0f9e7c66859",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-0003"
},
"signed": {
"signature": "03268a0a7ccb7a1e18cd99f60513ec9814f9d240",
"fields": "token created_at updated_at succeeded transaction_type state",
"algorithm": "sha1"
}
}
}
Spreedly’s Account Updater allows you to always keep your customers’ card details up-to-date. When your customers’ credit card numbers expire or are updated, Account Updater protects you from the lost revenue, involuntary churn, and decreased customer satisfaction associated with outdated payment information. No additional development is required on your side since cards are updated behind the scenes.
Learn more in our Account Updater Guide.
Each of the following statuses is a transaction_type, with the transactions being retrievable using a List or Show call. Request bodies are formatted identically for all request types, varying only in the value of the transaction_type field.
ReplacePaymentMethod
The number and/or expiration date has been updated.
InvalidReplacePaymentMethod
The card number or expiration date that we received was invalid. The payment method was not updated, and there is no charge.
ContactCardHolder
The card network identified this account needs to be updated but the issuer did not provide the updated values. Contact the cardholder for a new number and/or expiration date.
ClosePaymentMethod
The account is no longer open and should no longer be used. The payment method will remain available, but Spreedly’s Account Updater will no longer attempt to update it.
Network Tokens
Card Metadata
GET /v1/network_tokenization/card_metadata.<format>?payment_method_token=<payment_method_token> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 Success
{
"card_metadata": {
"backgroundColor": "0x7aff54",
"foregroundColor": "0x7aff54",
"labelColor": "0x7aff54",
"contactEmail": "test1@visa.com",
"contactNumber": "1-800-432-4357",
"contactName": "test contact",
"privacyPolicyURL": "https://www.freeprivacypolicy.com/",
"termsAndConditionsURL": "https://termsconditions.com/",
"termsAndConditionsID": "fa66dcacb71f426c80ed4b3c5e109cbf",
"shortDescription": "My Test Issuer",
"longDescription": "My Test Issuer",
"cardData": [
{
"guid": "4428da983173468a8435f056e4984997",
"contentType": "cardSymbol",
"content": [
{
"mimeType": "image/png",
"width": "100",
"height": "100"
}
]
}
],
"issuerFlags": {
"deviceBinding": true,
"cardholderVerification": true,
"trustedBeneficiaryEnrollment": true,
"delegatedAuthenticationSupported": true,
"oboDeviceBinding": true
}
}
}
<card_metadata>
<backgroundColor>0x7aff54</backgroundColor>
<foregroundColor>0x7aff54</foregroundColor>
<labelColor>0x7aff54</labelColor>
<contactEmail>test1@visa.com</contactEmail>
<contactNumber>1-800-432-4357</contactNumber>
<contactName>test contact</contactName>
<privacyPolicyURL>https://www.freeprivacypolicy.com/</privacyPolicyURL>
<termsAndConditionsURL>https://termsconditions.com/</termsAndConditionsURL>
<termsAndConditionsID>fa66dcacb71f426c80ed4b3c5e109cbf</termsAndConditionsID>
<shortDescription>My Test Issuer</shortDescription>
<longDescription>My Test Issuer</longDescription>
<cardData>
<guid>4428da983173468a8435f056e4984997</guid>
<contentType>cardSymbol</contentType>
<content>
<mimeType>image/png</mimeType>
<width>100</width>
<height>100</height>
</content>
</cardData>
<issuerFlags>
<deviceBinding>true</deviceBinding>
<cardholderVerification>true</cardholderVerification>
<trustedBeneficiaryEnrollment>true</trustedBeneficiaryEnrollment>
<delegatedAuthenticationSupported>true</delegatedAuthenticationSupported>
<oboDeviceBinding>true</oboDeviceBinding>
</issuerFlags>
</card_metadata>
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.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method to use |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| ❯ card_metadata | Contains various metadata for the card. |
| ❯❯ backgroundColor | Background color of the card, represented as a hex code. |
| ❯❯ foregroundColor | Foreground color of the card, represented as a hex code. |
| ❯❯ labelColor | Label color of the card, represented as a hex code. |
| ❯❯ contactEmail | Email address for cardholder contact. |
| ❯❯ contactNumber | Phone number for cardholder contact. |
| ❯❯ contactName | Name of the contact person for cardholder support. |
| ❯❯ privacyPolicyURL | URL to the privacy policy. |
| ❯❯ termsAndConditionsURL | URL to the terms and conditions. |
| ❯❯ termsAndConditionsID | Unique identifier for terms and conditions. |
| ❯❯ shortDescription | Short description of the card issuer. |
| ❯❯ longDescription | Detailed description of the card issuer. |
| ❯❯ cardData | Array of card data objects. |
| ❯❯❯ guid | Unique identifier for each content item. |
| ❯❯❯ contentType | Type of content (e.g., card symbol). |
| ❯❯❯ content | Array containing details of the content, including format and dimensions. |
| ❯❯❯❯ mimeType | MIME type of the content (e.g., image/png). |
| ❯❯❯❯ width | Width of the content, in pixels. |
| ❯❯❯❯ height | Height of the content, in pixels. |
| ❯❯ issuerFlags | Flags indicating various issuer-supported features. |
| ❯❯❯ deviceBinding | Indicates if device binding is supported. |
| ❯❯❯ cardholderVerification | Indicates if cardholder verification is supported. |
| ❯❯❯ trustedBeneficiaryEnrollment | Indicates if trusted beneficiary enrollment is supported. |
| ❯❯❯ delegatedAuthenticationSupported | Indicates if delegated authentication is supported. |
| ❯❯❯ oboDeviceBinding | Indicates if on-behalf-of device binding is supported. |
Token Status
GET /v1/network_tokenization/token_status.<format>?payment_method_token=<payment_method_token> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 200 Success
{
"token_status": "ACTIVE"
}
<token_status>ACTIVE</token_status>
Get the status of a tokenized card.
URL Parameters
| Parameter | Description |
|---|---|
| payment_method_token required |
The token of the payment method to use |
| format required |
One of json or xml |
Response Body
Notable response elements include:
| Element | Description |
|---|---|
| token_status | Indicates the status of the associated Network Token. |
Order and Pagination
By default, unbounded lists (transactions, gateways, payment methods etc…) are ordered and paginated (these calls will be identified as such in their respective sections).
Order
GET /v1/gateways.<format>?order=desc HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
Ordered responses are sorted by the created_at attribute, oldest first. In the case where multiple timestamps are the same those records are then sorted alphabetically on the token attribute to give a consistent ordering.
Use the order parameter to reverse the list order to most recent first. Here is an example of sorting gateways in descending order.
URL Parameters
| Element | Description |
|---|---|
| order | The order of the returned list. Default is asc, which returns the oldest records first. To list newer records first, use desc. |
Pagination
GET /v1/gateways.<format>?since_token=<since_token> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
By default, unbounded lists are returned in groups of 20 items. If there are more than 20 items in the list, use pagination to retrieve the next set of 20.
To enforce determinism in a real-time system, pagination is indexed based on a specific record (as opposed to just a page number as is common in many web apps). To paginate to the next page, simply pass in the token of the last record in the current result set.
For instance, if the token of the last gateway in the initial set of twenty gateways returned is CtehwikoMnllHsr3XFfAY1EzPkN, 7NTzuQfnaNU2Jr4cVgOt7jfTVGq, 5peSrvUfpp4iLjKNiyPKed3JRXl, JJbYU8kXU5vwjG80abdAMjC9ndT, a6LJxbv3VdqA93FD7WYJJvyH6DT, a3S4R6KZJXp65Gyj1B6hlqULi5X, 4xCOoqZGrHiTcKl4pZLO4R1K6yk, I9y3N4mHB0WdHBUQY47VBfns8LQ, E9KHL90AT90QX6LC9QBKf3MBJwt, ClOS8VungrQ75v597EdBiDcWL3S, UYUZnZApb2mKB3E6j4exfiXsjil, K6CXnUseeoGD9bCKeFgXf3BunqT, LphoROWxndaFJW8jgSx7PcNujSd, 3uJquMW9frXbaPRtV7ORqwzhtnz, 3dcbnaN1fJQGaDBx5iurxyMl93v, CYH94awhSYETnpoVYb1aNzSJZj9, 421a7welTNAHhEMWl7hU7fbAs9N, 54LlKR76UyVexlSzycgbcqP5E9U, 8Wn2ke2IlBUSKbGNiLx4IAvz9SM, 6GRp2ms2E19YRK3xpEJbMnMYC0y, use that as the since_token parameter to get the next set of 20 starting after that gateway.
URL Parameters
| Element | Description |
|---|---|
| since_token | The token of the item to start from (e.g., the last token received in the previous page if iterating through records) |
Response Codes
An API call’s HTTP response code can indicate an error state or some other degradation of service. See the following response codes and corresponding response bodies for common causes.
401 Access denied
GET /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 401 Access denied
{
"errors": [
{
"key": "errors.access_denied",
"message": "Unable to authenticate using the given environment_key and access_token. Please check your credentials."
}
]
}
<errors>
<error key="errors.access_denied">Unable to authenticate using the given environment_key and access_token. Please check your credentials.</error>
</errors>
The specified environment key and access secret do not exist, do not authenticate, or are not authorized to perform the given action. The request should not be retried without adding or modifying the authentication header.
Error response
| Element | Description |
|---|---|
| key | errors.access_denied |
| message | Human readable explanation of error |
Potential issues
| Cause | Resolution |
|---|---|
| No HTTP basic authentication was specified. | Be sure to pass in your API call credentials using HTTP basic authentication headers. |
| The environment key or access secret used to authenticate are incorrect. | Make sure to verify and update these values. |
| The access secret does not have the permissions necessary to access the environment or perform the specific action. | Be sure to generate an access secret for use in your application |
402 Account inactive
POST /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "stripe",
"login": "your Stripe API secret"
}
}
<gateway>
<gateway_type>stripe</gateway_type>
<login>your api secret key</login>
</gateway>
HTTPS/1.1 402 Payment required
{
"errors": [
{
"key": "errors.account_inactive",
"message": "Your environment (SJvv22RySSCgEeMoANtJ2ZOvQCC) has not been activated for real transactions with real payment methods. If you're using a Test Gateway you can *ONLY* use Test payment methods - ( https://docs.spreedly.com/test-data). All other credit card numbers are considered real credit cards; real credit cards are not allowed when using a Test Gateway."
}
]
}
<errors>
<error key="errors.account_inactive">Your environment (SJvv22RySSCgEeMoANtJ2ZOvQCC) has not been activated for real transactions with real payment methods. If you're using a Test Gateway you can *ONLY* use Test payment methods - ( https://docs.spreedly.com/test-data). All other credit card numbers are considered real credit cards; real credit cards are not allowed when using a Test Gateway.</error>
</errors>
The requested action requires an active and paid account. The request should not be retried without first upgrading to a paid plan.
Error response
| Element | Description |
|---|---|
| key | errors.account_inactive |
| message | Human readable explanation of error |
Potential issues
| Cause | Resolution |
|---|---|
| The organization tied to the environment being accessed is not on a paid plan | Sign up for a paid plan. |
| The operation used a real payment method or production gateway during a test operation | Be sure to only use the test gateway type with test payment methods |
404 Not found
GET /v1/gateways/bad-token.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 404 Not found
{
"errors": [
{
"key": "errors.gateway_not_found",
"message": "Unable to find the specified gateway."
}
]
}
<errors>
<error key="errors.gateway_not_found">Unable to find the specified gateway.</error>
</errors>
The requested item was not found. The request should not be retried.
Error response
| Element | Description |
|---|---|
| key | errors.<item>_not_found where item is the type of record being requested (gateway, transaction, etc…) |
| message | Human readable explanation of error |
Potential issues
| Cause | Resolution |
|---|---|
| The specified token represents an item (gateway, payment method etc…) that does not exist in the authenticated environment. | Specify the correct environment key in the API call authentication. |
| The requested item does not exist (in any environment) | Retry with an existing item token |
406 Not acceptable
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 406 Not acceptable
The request includes an invalid or unsupported Accept header. Ensure that the headers are valid before trying again. Otherwise, the request was blocked by a security rule and should not be retried.
Potential issues
| Cause | Resolution |
|---|---|
| The request included an invalid or unsupported Accept header | Ensure your accept header is one of */*, application/json, or application/xml |
| The request was flagged as a security risk | Make sure the request does not contain malformed or malicious content |
| The request was sent to a restricted endpoint | Make sure the request is sent to a valid endpoint |
| The request was received from a restricted IP address | If all requests from this IP address result in a 406 response, submit an issue to Spreedly support |
408 Request timeout
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 408 Request Timeout
The external service, such as a gateway, did not respond within the request timeout period or experienced a connection error. In these situations, it is impossible to determine the final state of the transaction and the transaction state will be set to gateway_processing_result_unknown. This is a fundamental issue in distributed systems - if a reply isn’t received, the result can’t be known.
If you receive a 408 for a transaction where actual money is changing hands (like a purchase or a capture), check with the third party (gateway, receiver, etc…) to determine what the real result was before retrying.
Potential issues
| Cause | Resolution |
|---|---|
| The gateway or other external service did not response in a timely manner | Check the gateway to determine the final status of the transaction before attempting a retry |
| There was a connection error communicating with the external service | Check the gateway to determine the final status of the transaction before attempting a retry |
415 Unsupported media type
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 415 Unsupported Media Type
The request includes an invalid or unsupported Content-Type header. Ensure that the headers are valid before trying again.
Potential issues
| Cause | Resolution |
|---|---|
| The request included an invalid or unsupported Content-Type header | Ensure your content-type header is application/json or application/xml |
422 Request not processed
The request could not be processed. An error message with more detail may be present in the response. See the list of potential issues for known cases.
PUT /v1/gateways/<gateway_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "stripe"
}
}
<gateway>
<gateway_type>stripe</gateway_type>
</gateway>
HTTPS/1.1 422 Unprocessable Entity
{
"errors": [
{
"message": "You may not change the gateway_type of a gateway.",
"key": "errors.gateway_gateway_type_cannot_be_changed"
}
]
}
<errors>
<error key="errors.gateway_gateway_type_cannot_be_changed">You may not change the gateway_type of a gateway.</error>
</errors>
Error response
| Element | Description |
|---|---|
| attribute | optional The specific field that failed validation |
| key | errors.<offending_item> a key indicating the type of error experienced |
| message | Human readable explanation of error |
Potential 422 issues
| Cause | Resolution |
|---|---|
The payment method is redacted, closed, or used |
This payment method cannot be used and the request should not be retried. The result in this case will include a full transaction response and token. |
| The request is not valid | Verify the request matches the format and value types specified in our API reference, correct it and retry |
| There was difficulty communicating with the gateway | Check the status page to see if there is a known issue, or submit an issue to Spreedly support |
| There was a problem with the gateway’s response to Spreedly | Submit an issue to Spreedly support |
429 Too many requests
There have been too many API calls against a rate-limited endpoint.
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 429 Too Many Requests
Rate limited endpoints
| Endpoint | Path | Rate limit |
|---|---|---|
| List transactions | /v1/transactions.<format> |
30 requests per minute, per environment |
| Create credit card | POST /v1/payment_methods.<format> |
1000 requests per 24 hours, per first-six, last-four, and environment OR 250 requests per 24 hours, per first-eight, last-four, and environment |
| List supported receivers | GET /v1/receivers_options.<format> |
30 requests per min, per environment |
| List receivers | GET /v1/receivers.<format> |
30 requests per min, per environment |
| Create receiver | POST /v1/receivers.<format> |
30 requests per min, per environment, indiscriminate of http or sftp receiver |
| Show receiver | GET /v1/receivers/<receiver_token>.<format> |
30 requests per min, per environment |
| Update receiver | PUT /v1/receivers/<receiver_token>.<format> |
30 requests per min, per environment |
| Redact receiver | PUT /v1/receivers/<receiver_token>/redact.<format> |
30 requests per min, per environment |
| List certificates | GET /v1/certificates.<format> |
30 requests per min, per environment |
| Create certificate | POST /v1/certificates.<format> |
30 requests per min, per environment |
| Generate certificate | POST /v1/certificates/generate.<format> |
30 requests per min, per environment |
| Update certificate | PUT /v1/certificates/<certificate_token>.<format> |
30 requests per min, per environment |
503 Service unavailable
Spreedly is temporarily unable to process the request.
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 503 Service Unavailable
{
"errors": [
{
"key": "errors.circuit_breaker_open",
"message": "Spreedly detects a payment gateway outage, recommend retrying transaction on a backup gateway",
"gateway_name": "Bogus"
}
]
}
<errors>
<error key="errors.circuit_breaker_open" gateway_name="Bogus">Spreedly detects a payment gateway outage, recommend retrying transaction on a backup gateway</error>
</errors>
Potential issues
| Cause | Resolution |
|---|---|
| There are persistent errors while communicating with the gateway, leading Spreedly to temporarily halt requests to this gateway | Retry the request in 60 seconds, or set up a backup gateway using Spreedly Transaction Retry |
| Spreedly is experiencing general instability | Check the status page to see if there is a known issue and the expected resolution time |
500 Level Errors
Other 500 level errors (such as 500, 502 and 504 for example) are application errors which indicate that the API cannot handle a request. Please contact Spreedly support regarding specific transactions that receive this response.