API implementation
After provisioning a gateway via our gateway user guide, creating at least one workflow, and collecting payment information, the next step is to enable authorizations, purchases and other transactions. These API calls are part of the overall transaction flow and will need to be called in order to complete a transaction with Spreedly to the gateway designated in your workflow.
Our orchestration platform normalized API support through our /transactions endpoint (https://core.spreedly.com/v1/transactions) which is managed by our Workflow service. When a transaction is sent to /transactions, our Workflow service will determine how the transaction will be processed based on the Workflow you created in our low code user interface. Both XML and JSON format are supported. A workflow_key should be sent in the request body or left as null to evoke the Default Workflow.
Although gateway specific fields and gateway specific response fields are supported, below is an example of the many normalized fields supported by Composer.
{
"transaction": {
"payment_method_token": "5MIKle5jHox1RRxnYaclAhmjNfR",
"amount": 100,
"currency_code": "USD",
"workflow_key": "be2bf321f1b440ffa654a93de9b4fab4"
},
"amount": 70,
"currency_code": "USD",
"risk_data": {
"ignore_cvv": true,
"ignore_avs": false,
"ignore_fraud_rules": "true",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
},
"customer_data": {
"merchant_customer_id": "a_customer_id_1"
},
"merchant_metadata": {
"statement_descriptor": {
"description": "TES",
"phone_number": "123-456-7891",
"url": "something.com",
"suffix": "-EX"
},
"transacting_account_id": "12345"
},
"order_data": {
"invoice_id": "INV_123",
"shipping_amount": 10,
"discount_amount": 20,
"tax_amount": 10,
"shipping_from_zip": "12345",
"quantity": 2,
"description": "Vending Machine",
"fulfillment_date": "07/29/2024",
"gateway_idempotency_key": "123",
"installment_count": "5",
"order_content": "vending",
"network_transaction_id_override": "1234567890",
"zero_dollar_auth": "false",
"line_items": [
{ "product_code": "SKU-123",
"description": "an item",
"quantity": 1,
"unit_cost": 40,
"tax_amount": 5,
"discount_amount": 10,
"total_amount": "20",
"reference": "ORDER_123",
"sale_kind": "debit",
"item_name": "Water Bottle"
},
{
"product_code": "SKU-321",
"description": "two of the same",
"quantity": 2,
"unit_cost": 20,
"tax_amount": 5,
"discount_amount": 10,
"total_amount": "20",
"reference": "ORDER_123",
"sale_kind": "debit",
"item_name": "Chips"
}
]
}
}
}
{
"transaction": {
"on_test_gateway": true,
"created_at": "2024-05-10T14:47:09Z",
"updated_at": "2024-05-10T14:47:10Z",
"succeeded": true,
"state": "succeeded",
"token": "4LlUFb7X8au2XkVDSxfmgZhnuM9",
"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_transaction_id": "4LlUFb7X8au2XkVDSxfmgZhnuM9",
"sub_merchant_key": null,
"gateway_latency_ms": 830,
"warning": null,
"application_id": null,
"risk_data": {
"ignore_avs": false,
"ignore_cvv": true,
"user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
},
"merchant_metadata": {
"statement_descriptor": {
"description": "TES",
"phone_number": "123-456-7891",
"url": "something.com",
"suffix": "-EX"
}
},
"customer_data": {
"merchant_customer_id": "a_customer_id_1"
},
"order_data": {
"discount_amount": 20,
"shipping_amount": 10,
"shipping_from_zip": "12345",
"tax_amount": 10,
"invoice_id": "INV_123"
},
"amount": 70,
"local_amount": null,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": true,
"smart_routed": false,
"workflow_key": "5MIKle5jHox1RRxnYaclAhmjNfR",
"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": "13K7GGE3FX9QRSY2DF28P9TEWX",
"gateway_type": "worldpay",
"gateway_response": {
"card_metadata": {
"issuer_country": "N/A",
"card_type": "credit"
},
"merchant_data": {
"fraud_result": "21"
},
"raw_payment_outcome_data": {
"raw_cvc_result": "C",
"raw_avs_result": "E",
"network_transaction_id": "060720116005062"
}
},
"response": {
"success": true,
"message": "SUCCESS",
"avs_code": "I",
"avs_message": "Address not verified.",
"cvv_code": "P",
"cvv_message": "CVV not processed",
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2024-05-10T14:47:10Z",
"updated_at": "2024-05-10T14:47:10Z",
"network_transaction_id": "060720116005062"
},
"shipping_address": {
"name": "Joe Smith",
"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": "8kJRMTENOt2zfpzEkcm31T3UP6Z",
"created_at": "2024-05-10T14:47:09Z",
"updated_at": "2024-05-10T14:47:09Z",
"email": "[email protected]",
"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": 2025,
"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 Smith",
"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": null,
"bin_metadata": {
"message": "BIN Metadata is available only to Advanced Vault enrolled customers and payment methods. Reach out to your account representative for more details."
},
"payment_method_type": "credit_card",
"errors": [],
"fingerprint": "e0e90dbbe3e88a2a9e079f520c0b7a69a6ef",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
Please refer to the API reference docs linked below for more details on the request and response formats:
Authorize and Purchase Endpoints
- transactions/purchase: This API will package an Authorize and Capture into a single request to the gateway specified in the workflow which is denoted from the workflow token in the request body.
- transactions/authorize: This API will trigger an authorization request to the gateway specified in the workflow which is denoted from the workflow token in the request body.
Other Endpoints
These APIs are completely optional and may or may not apply depending on your business logic and transaction flow.
- transactions/verify: This API will determine if a credit card is a chargeable card and available for purchases.
- transactions/:id/capture: By passing in the transaction token from the Authorize, this call will initiate a Capture of the established authorization.
- transactions/:id/credit: This call will refund a full or partial amount of a previously captured transaction or credit a stored payment method token. You will need to pass in the Capture transaction token in order to issue the refund.
- Note: General credits (unlinked refunds) are initiated by the gateways/:id/general_credit endpoint only and are available based on the gateway. Please refer to the gateway's guide for more details.
- transactions/:id/void: Cancel an authorization transaction or a capture/purchase transaction that hasn’t yet settled at the merchant account.
Updated 21 days ago