Run transactions

After provisioning a gateway in an environment and collecting payment information, the next step is to enable purchases and other transactions.

Transaction lifecycle

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 your desired gateway/PSP.

1. Purchase - This API will package an Authorize and Capture into a single request through the gateway/PSP denoted in the request URL (via the gateway token provided). The amount is always given as an integer number of cents.
   • 2-decimal currencies should be shifted two digits (e.g. for a purchase of $12.34 , pass an amount of 1234)
   • 3-decimal currencies should be shifted three digits (e.g. for a purchase of $1.234, pass an amount of 1234)
   • 0-decimal currencies should have the “implicit decimal” shifted two digits, appending two 0's (e.g. for a purchase of $1234, pass an amount of 123400)
2. Authorize - This will trigger an authorization request only through the gateway/PSP denoted in the request URL (via the gateway token provided).
3. Capture - By passing in the transaction token from the Authorize, this call will initiate a capture of the established authorization.

Payment orchestration

These calls are completely optional and may or may not apply depending on your business logic and transaction flow.

1. Retain - By default, when a payment method is added to Spreedly, it is placed in a “cached” storage state. This state indicates that unless told otherwise, the card will be purged from Spreedly after a short period of time (approximately 12 hours). If you are performing a one-time transaction in which you collect payment information and then immediately charge the card, then you don’t need to do anything else. However, if you want to charge the card again in the future or if you have a longer period of time between collecting the payment information and executing a purchase, then you will need to retain the card. If you don’t want to automatically retain a card when it’s used in a transaction, you can omit the retain_on_success parameter.
   • Since it’s so common to want to keep valid cards around for future purchases, Spreedly provides a retain_on_success parameter that can be used to automatically retain a card when it’s used in a successful transaction.
     • Note: In this scenario, the initial transaction response from the Spreedly API will show that the payment method’s storage_state is cached even if the transaction was successful. This is because the response shows a snapshot of the payment method at the time the transaction was executed. The storage_state will be updated to retained immediately after the transaction succeeds.
2. Redact - When you no longer need to store a card and want to remove it from Spreedly, you can redact it. Redacting a card will wipe all sensitive information related to the payment method and make the card inoperable.
3. Verify - This call will package an authorization and subsequent void of that transaction for the purposes of checking the status of the payment method being used, and is subject to gateway support. It is recommended that the field retain_on_success is set to true for these calls in order to retain the payment method token in the Spreedly vault for future use. If using network tokenization, then you will also need to pass a request field of provision_network_token set to true.
4. Credit/Refund - This call will refund 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. You may directly credit a payment method token by passing the payment method token instead of the transaction token; however, this is subject to gateway support.
5. List - Retrieve an ordered and paginated list of all retained payment methods in the authenticated environment.