Transaction Flows

Integrating with Switch

Supporting different Payment Methods under the same platform in a standardized manner brings additional challenges when it comes to transaction execution. Each Payment Method is designed with its own philosophy when it comes to processing Transactions, and therefore requires different steps, and different execution flows.

Accommodating this diversity under the same Platform required us to support four Transaction Flows. These include Capture on Creation, Auth-Capture, Recurring on Auth, and Recurring on Capture.

Transaction Flow	Payment executed automatically?	Recurring Payment?
1. Capture on Creation	Yes	No
2. Auth-Capture	No	No
3. Recurring on Auth	Yes	Yes
4. Recurring on Capture	No	Yes

Capture on Creation

This flow targets transactions that only need to take place once, and where the funds do not need to be captured at a later time, therefore not requiring an authorization to take place.

From a Switch Platform perspective, this flow does not require you to create the Payment element to execute the funds transfer. The Processing Application will automatically create the Payment element once you create the Instrument, given that the funds will be captured right away.

Example usage: payment of digital goods.

Recurring on Auth

Destined for Payments that need to happen on a frequent basis, this flow allows you to create a reusable Instrument element that can be leveraged to make multiple Payments.

This particular recurring flow automatically executes the Payment element when the Instrument is created. It means that for the first payment, you only need to create the Instrument, as the Switch platform will automatically create the first Payment. For subsequent Transactions you only need to create the Payment element, referencing the same specific Instrument.

Example usage: subscriptions.

Auth-Capture

An Auth-Capture flow is intended for Transactions that take place once, and have the funds captured at a later time, thus requiring two steps: authorization and funds capture.

The authorization is executed when the Instrument element is created in our platform, either automatically using our Dynamic Forms or manually leveraging our REST API. At this stage the money has been reserved from the customer accounting platform but has not yet been transferred. The actual funds transfer only happens when the Payment element is created in the Switch Platform.

Example usage: hotel or rental car bookings.

Recurring on Capture

Designed for transactions that need to take place regularly, enables you to create a reusable Instrument element that can be used to perform multiple Payments.

This particular recurring flow does not automatically execute the Payment element when the Instrument is created. In short, it requires you to create a Payment element every time you want to execute a transaction.

Example usage: subscriptions.

Instrument Flows

Depending on the Payment Method, after creating an Instrument on the client-side, one of three things might happen.

If the Payment is synchronous, the flow will end in success, and the customer can be shown the success screen.

Example: Credit Card.

If the Payment requires the Customer to push funds using an account reference this reference should be displayed to the Customer, or the Dynamic Forms can show it for you.

Example: Multibanco, by going to an ATM.

If the payment requires redirection, the Dynamic Forms will redirect the customer to the Payment Provider page for authentication. Afterward, it will redirect back to your server's redirectUrl with an Instrument id parameter with which you can confirm the Instrument status.

Example: Paypal.

To support redirection, you should add a redirectUrl on the charge creation. For convenience, you can simply add it for all Transactions, even if it is not necessary.

REQUEST
    $ curl -vX POST https://api-test.switchpayments.com/v2/charges
   -u accountId:privateKey
   -d '{
     "charge_type": "card_onetime",
     "amount":42,
     "currency":"EUR",
     "redirectUrl":"https://www.merchant.com/redirectUrl"
   }'

Capturing Funds at a Later Time

Depending on the Payment Method, there are specific server-side operations that can be enabled after redirecting.

If the Instrument is not captured on creation, it means that the funds have been authorized/reserved and can be captured/transferred in a future time.
If the Instrument is recurring, it means that the Customer has authorized multiple Payments to be created.

In both these cases, the instrument id should be saved on your database during the instrument.authorized Event and used to create a Payment at any time, by calling the Payments endpoint using the Instrument.

REQUEST
    $ curl -vX POST https://api-test.switchpayments.com/v2/payments
   -u accountId:privateKey
   -d '{
     "instrument": "4145f3be2094da8b786fe9ab5c6ed206d7c2e",
     "amount":42,
     "currency":"EUR"
   }

Result Parameters

idString

Payment id, to be used for refunds.

successString

Payment success status.

refundableBoolean

Whether refunds can be created for this payment

RESULT HTTP 201
    {
     "id": "206d7c2e4145f3be2b786fe9ab5c6ed094da8",
     "success": true,
     "refundable": true
  }

Refunding Transactions

If a Payment is refundable, you can call its refund method using the Private Keys.

REQUEST
    $ curl -vX POST https://api-test.switchpayments.com/v2/refunds
   -u accountId:privateKey
   -d '{
     "amount":42,
     "currency":"EUR",
   }

RESULT HTTP 201
    {
     "success": true
  }

Result Parameter

successBoolean

Boolean that marks whether transactions are successful or unsuccessful.