First Data provides a REST API for merchants and partners to integrate payment functionality and value added services across First Data product suites.
In relation to the First Data Gateway, the REST API offers resources for Payments and Orders.
Payments consist of primary and secondary transactions, while Orders is the logical grouping of payment transactions. The payments flow is divided into primary and secondary transaction types.
- Primary transactions are the main payment types and can be run independently
- Secondary transactions require an initial primary transaction
Additionally, the API Payments resource supports optional fields that allow information specific to an industry (e.g. airline, lodging, car-rental, etc.) to be transferred with the payment request.
Primary Transactions are the main payment transactions that can be run independently. They include:
- Sale - A transaction that authorizes and captures the funds from the payment instrument.
Supported Sale transactions include recurring transactions where the merchant charges for goods or services at a defined frequency (for example, monthly). A Sale transaction can be marked as a recurring transaction by sending appropriate data as described in the API Reference.
- Pre-Authorization - A transaction that verifies that the funds are available through the payment instrument but does not capture those funds. A hold is placed on the funds for up to 7 days. If the transaction is not completed within that time, the transaction is marked as voided and cannot be completed.
- Credit - A transaction that transfers funds from the merchant to the customer.
- Forced Ticket - A transaction that immediately captures a transaction previously authorized outside of the payment gateway (for example, by phone.) This requires an authorization code from the authorized transaction.
Please note that if you plan to collect your customer's card details within your environment and send it to our API, you must ensure that your system components are PCI DSS compliant.
Secondary Transactions are additional actions that can be done to change the state of an already existing Primary Transaction. These include:
- Postauth - Completion of a Pre-Authorization transaction. A Postauth transaction can complete a Pre-Authorization transaction either completely or partially.
- Void - A transaction that reverses a previous transaction. A Void can be applied to the following transactions: Sale, Preauth, Credit, Forced Ticket, Postauth, Return
- Return - A transaction that credits a customer account after goods or services have been returned. The return transaction can be applied in full or partially to a previous transaction.
- Split Shipment - A transaction that charges for only part of the goods or services on a Pre-Authorization transaction. The last of a series of Split Shipments should tag the finalShipment element as 'true' in order for the pre-authorized transaction to be closed.
An Order is a way to combine related transactions in a logical sense. An order can contain one primary transaction and multiple secondary transactions. For example:
- Pre-Authorization transaction of $100, followed by
- One Postauth (completion) of $30 at the first shipment, followed by
- One Postauth (completion) of $10 at the second shipment.
- One Sale of $100, followed by
- One partial Return of $20, followed by
- One Void of the partial Return
Orders can be queried by orderId directly or by filter of range on first, maxCount, orderBy date, etc. An Order can be "Return"ed, which is the Return transaction on the primary transaction in the order. Partial Returns are allowed.