REST Integration

Integrating with Switch

In case it is not possible to implement a specific flow using Dynamic Forms, the data collection can be performed by a Merchant customized form and sent to Switch using our REST Processing API.

This integration should be used for scenarios where Dynamic Forms are not practical. This can include, custom transaction flows, for instance, authentication parameter collection split into multiple steps and webpages, or host-to-host communication that demands different compliance dynamics.

For REST Integration you should consider the following order of instructions:

Display Form
Create Charge
Create Instrument
Alternative Flows: Reference and Redirection

Display Form

Although this integration pattern does not provide a client-side library to render the UI, it still allows you to dynamically support new Payment Methods.

In order to do so, our API provides an endpoint that will describe which Payment Methods are currently active for your account and the corresponding fields that should be captured from the user, these make the form schema. This information allows you to construct the UI in a dynamic manner, ensuring it can accommodate future changes and allowing you to truly leverage our Dashboard management capabilities to activate Payment Channels at will.

Path	Method	Description
https://api-test.switchpayments.com/v2/charges/types	GET	Lists the Charge types currently active for this account.

REQUEST EXAMPLE
    $ curl https://api-test.switchpayments.com/v2/charges/types
    -u publicKey

RESPONSE EXAMPLE
  [
   "...",
   {
     "id": "card",
     "title": "Credit/Debit Card",
     "schema": {
       "required": ["name", "number", "expiration_month", "expiration_year", "cvv"],
       "properties": {
         "name": {
           "title": "Cardholder Name",
           "type": "string",
           "minLength": "3",
           "maxLength": "255"
         },
         "expiration_month": {
             "title": "Expiration Month",
             "type": "integer",
             "minimum": "1",
             "maximum":"12"
         }
     }, "..."
     },
     "ui_schema": {
       "name": {"ui:placeholder": "Full Name"},
       "number": {"ui:placeholder": "1111 2222 3333 4444"},
       "cvc": {
         "ui:placeholder": "123",
         "ui:help": "Last 3 digits on the back of the card"  
       }, "..."
     }
   },
   "..."
  ]

The payload returned by this endpoint can be leveraged by your client-side library to construct the UI with the active Payment Methods, gather the required data from the user, and validate it accordingly. This will grant a higher deal of flexibility to your frontend implementation, allowing you to seamlessly support future changes.

Create Charge

As stated in the Core Concepts section, our Platform divides a Transaction into three executable Elements: Charge, Instrument, and Payment. The API allows you to coordinate the creation of these Elements, where required, through multiple available endpoints.

In order to generate a Charge, the following endpoint should be called by your backend platform using your Private API Key.

Path	Method	Description
https://api-test.switchpayments.com/v2/charges	POST	Creates a new Charge for a given transaction.

Request Body Params

charge_typeStringRequired

Indicates the Payment Method that has been selected by the Customer, should contain the value passed by our API call. For a list of updated values please contact our Integration Team.

currencyStringRequired

ISO 4217 code that indicates the currency that will be used by the Transaction.

amountNumberRequired

The amount that should be charged to the Customer.

events_urlString

Allows you to configure the URL that will be called by the Switch Platform to notify about Lifecycle Events related to this Transaction. Please note that the URL must use HTTPS.

redirect_urlString

Specifies the HTTPS URL to where the users should be sent after they authenticated the Transaction on the Payment Method page.This parameter is only required for Payment Methods that require user redirection for authentication (e.g. PayPal).

instrument_paramsJSON Object

Specifies configuration parameters that are passed to the Provider when creating the Instrument element and which allow you to configure how the fund transfer is executed.

metadataJSON Object

This object allows you to pass any Transaction related data points that may be useful to be displayed in the Switch Dashboard for analysis purposes.

channelsArray

Gives the ability to specify which Channel should be used to process the transaction. Using this parameter you can leverage your business logic to select the Channel rather than relying on Switch’s Dynamic Routing. If multiple values are present, a fallback mechanism will be used, giving precedence to the first entries

REQUEST EXAMPLE
    -u accountId:privateKey
    -d '{
      "charge_type": "card_onetime",
      "amount": 42,
      "currency": "EUR",
      "events_url": "https://your.url/v1/notificationHandler"
    }'

Response Body Params

idString

The id that uniquely identifies the created Charge element for this Transaction.

charge_typeString

Indicates the Payment Method that will be used to process the Transaction.

charge_type_labelString

User-friendly description of the Payment Method that will be used to process the Transaction.

currencyString

ISO 4217 code that indicates the currency that will be used by the Transaction.

amountNumber

The amount that will be charged to the Customer.

confirmedBoolean

Indicates whether the current Charge element has been confirmed by the Merchant using their private key.

externalBoolean

Indicates whether the current Charge element was not created by the Switch Platform.

instrument_paramsJSON Object

The configuration parameters that were specified when creating the Charge element, which allow you to configure how the funds transfer is executed by the Provider.

events_urlString

Contains the URL that will be called by the Switch Platform to notify about Lifecycle Events related to this transaction.

redirect_urlJSON Object

The URL to where the users should be sent after they authenticated the transaction on the Payment Method page.

channelsArray

Documents the Channels that will be used to process the Transaction.

metadataJSON Object

The Transaction related data points that were passed when creating the Charge, which may be useful to be displayed in the Switch Dashboard for analysis purposes.

external_idsJSON Object

Documents the Provider id for the current Charge, if available.

request_logJSON Object

Stores information about the device that was used to create the current Charge element, such as country, ip_address, user_agent, and library_version.

created_atString

Indicates the date and time when the current Charge element was created.

updated_atJSON Object

Documents the date and time when the last update was performed to the current Charge.

RESPONSE EXAMPLE
    {
    "id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
    "charge_type": "card_onetime",
    "amount": 10,
    "currency": "EUR",
    "confirmed": false,
    "external": false,
    "instrument_params": {
        "enable3ds": true
    },
    "events_url": "https://merchant.com/events",
    "channels": [{
        "processor": "checkout",
        "id": "85a557e4fdb6c8806f413bc75fabab162828e4f95b8e6390",
        "label": "card_onetime_checkout"
    },
    {
        "processor": "acapture",
        "id": "9fb7b1e253f1c592210b7c37b40b18e576ff30995b8e40de",
        "label": "card_onetime_acapture"
    }],
    "charge_type_label": "Card One-Time",
    "redirect_url": "https://merchant.com/redirect",
    "metadata": {
        "orderId": "1337"
    },
    "external_ids": null,
    "request_log": {
        "country": "PT",
        "ip_address": "100.10.10.10",
        "user_agent": "curl/7.54.0",
        "library_version": null
    },
    "created_at": "2018-06-18T10:28:36.358233+00:00",
    "updated_at": "2018-06-18T10:28:36.358258+00:00"
  }

Create Instrument

At this stage in Payment processing, we need to collect the required information from the Customer to execute the Payment. This procedure will be performed by your checkout page, leveraging your frontend framework, which should collect the parameters required depending on the Payment Method selected by the Customer.

Once this is completed, your UI component should create the Instrument element using the following endpoint.

Path	Method	Description
https://api-test.switchpayments.com/v2/instruments	POST	Creates a new Instrument for a given transaction.

Request Body Params

chargeStringRequired

The unique identifier for the Charge element that was previously created for this Transaction.

currencyStringRequired

The remaining fields are dependent on the Payment Method that was previously selected. Below you can find an example for card_onetime.

nameString

The name of the Cardholder, as printed on the card.

numberInteger

The number of the card that will be used to process the Payment. It should contain 14 to 19 digits, without any separators.

expiration_monthInteger

Zero padded, two-digit representation of the expiration month for the card.

expiration_yearInteger

Zero padded, two-digit representation of the expiration year for the card.

cvcString

The card verification code should contain 3 to 4 digits according to the card brand.

REQUEST EXAMPLE
    $ curl -vX POST https://api-test.switchpayments.com/v2/instruments
      -u publickey:
      -d '{
          "charge": "35ed95bfb772b94c4e59f91fcbef0f5618d46e3d5b2b7da5",
          "name": "John doe",
          "number": "4111111111111111",
          "expiration_month": 12,
          "expiration_year": 2018,
          "cvc": "007"
      }'

Response Body Params

idString

The id that uniquely identifies the created Instrument element for this transaction.

fingerprintString

A unique, one-way hash fingerprint of the current this Instrument, which can be leveraged for Risk prevention purposes.

successBoolean

This boolean flag indicates if the current Instrument has been successfully executed. true: the Instrument has been successfully executed. false: the Instrument has failed to be executed.

statusString

Documents the execution status for the Instrument. authorized: the Instrument was successfully authorized by the Provider. invalid: the Instrument was considered invalid by the Switch platform or the Provider. pending: used for asynchronous Payment Methods, indicates that the Customer is yet to provide additional information to proceed forward.

responseJSON Object

Contains the technical information returned by the Provider when processing the current Instrument, such as the card ECI code.

failure_descriptionString

Used for scenarios where the Instrument fails to be created, this parameter will contain a textual description of the error.

usedBoolean

Indicates if the current Instrument has been previously used. true: the Instrument has been used to perform a previous transaction. false: the Instrument is yet to be used to perform a transaction.

last_paymentJSON Object

Used for recurring payments, stores information about the previous payment executed with the current Instrument: id, success, failure_code, failure_description, and processor_failures.

redirectJSON Object

Used for Payment Methods that require redirection, documents the information required to direct the user to the page where he will complete the Transaction: url, method, params.

referenceJSON Object

Only applicable to Payment Methods that require the Customer to complete the Transaction asynchronously outside of the Switch platform. Documents the information required by the Customer to be able to do so, the specific schema of this object will be dependent on the Payment Method.

externalBoolean

Indicates whether the current Instrument element was not created by the Switch Platform. true: the Instrument has not been processed by the Switch platform. false: the Instrument has been created using the Switch platform.

channelsJSON Object

Documents the Channel that was used to process the Instrument.

chargeJSON Object

Basic Charge information.

external_idsJSON Object

Documents the Provider id for the current Instrument, if available.

request_logJSON Object

Stores information about the device that was used to create the current Instrument element, such as: country, ip_address, user_agent, and library_version.

created_atString

Indicates the date and time when the current Instrument element was created.

updated_atString

Documents the date and time when the last update was performed to the current Charge.

RESPONSE EXAMPLE
  {
     "id": "0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc",
     "status": "pending",
     "customer": null,
     "used": false,
     "last_payment": null,
     "redirect": {
         "url": "https://api.switchpayments.com/v2/instruments/0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc/redirect",
         "method": "GET",
         "parameters": null
     },
     "reference": null,
     "response": {
         "eci_code": "05"
     },
     "params": {
         "bin": "411111",
         "name": "John doe",
         "expiration_year": 2018,
         "brand": "VISA",
         "expiration_month": 12,
         "fingerprint": "a1ccb846ceda84e80b91bee9025437b73784de262233a1bde39490bcb597fb69ef51d9dd3f67a2cb4ee85fb67410460f138f9bb1ee5d7de2f27291e7e895f7a8",
         "enable3ds": true,
         "last_4_digits": "1111"
     },
     "external": false,
     "success": true,
     "failure_description": null,
     "channel": {
         "processor": "checkout",
         "id": "85a557e4fdb6c8806f413bc75fabab162828e4f95b8e6390",
         "label": "card_onetime_checkout"
     },
     "charge": {
             "charge_type": "card_onetime",
             "currency": "EUR",
             "created_at": "2018-06-21T10:27:49.241769+00:00",
             "charge_type_label": "Card One-Time",
             "amount": 10,
             "id": "35ed95bfb772b94c4e59f91fcbef0f5618d46e3d5b2b7da5"
     },
     "external_ids": {
         "processor": "8a8294496421b8d30164222227f17687"
     },
     "request_log": {
         "country": null,
         "ip_address": "100.10.10.10",
         "user_agent": "curl/7.54.0",
         "library_version": null
     },
     "created_at": "2018-06-21T11:37:01.694149+00:00",
     "updated_at": "2018-06-21T11:37:01.694168+00:00"
  }

Alternative Flows

Reference

For payment methods that require the Customer to push funds using an account reference. The reference fields should be displayed to the customer.

Example usage: Multibanco, by going to an ATM.

Redirection

For payment methods that require redirecting the user to a Provider page. After creating the Instrument, the app should redirect the user to https://api-test.switchpayments.com/v2/instruments/ + instrument.id + /redirect. After that, the user will be redirected to the redirectUrl defined in the Charge.

Example usage: PayPal.

That's it!

By following these steps, your product is already enabled for many Payment Methods and Providers, and your integration is ready to be tested. Please contact us if you have any feedback or need help integrating. We want to make this integration as simple as possible, and depending on your server-side language or CMS, we might even be able to provide you with code samples.

Next Steps

Create your events_url and handle Transaction Lifecycle Events. This process will allow you to mark transactions as paid in your database. Get to know a few additional Transaction Flows you should handle to truly support every Payment Method, Provider, and Transaction Flow in the world.