Processing

Every payment flow, one integration.

A key element of the Switch Platform is its ability to process transactions and leverage the resulting data to feed the Reconciliation, Risk, and Analytics Applications.

Transactions represent a central role in the Switch Platform, around which all its components have been devised. This led us to create an API solely dedicated to performing operations on transactions - the Processing API. These operations include the mechanisms mentioned bellow and can be applied to multiple types of elements. In the Processing API we highlight charge, instrument, payment, reversal and refund.

1
Create charge, instrument, and payment
Multiple single events make up the different Switch Platform elements. Quickly understanding how to create them and the requirements needed to do so, can speed up your process. Explore how to create charges, instruments and payments.
2
Refund and reversal
Sometimes transactions do not carry their natural course. When it comes to interacting with consumers about reversing a charge or setting up a refund, you can use our Processing API.

Charge

A charge represents the merchant request to either pull funds or push funds into a customer’s account.

Instrument

The instrument encompasses the data used to authenticate the customer.

Payment

A payment is a transaction authorization from a provider.

Reversal

Reverse a payment before it officially goes through.

Refund

After the transaction has been completed and before the customer has filled an official dispute, refunds are the right method to reverse a payment.

Channels

Combine payment methods and providers of choice. Each channel opens a world of opportunity for your payment operations.

Charge

A charge represents the merchant request to either pull funds or push funds into a user’s account. When dealing with charges, you should be mindful of the payment channel , also known as charge_type, the amount, the currency and the necessary metadata for transaction reconciliation, such as user ID and order ID. The charge is the precursor to the instrument.

GET `/v2/charges/types`

Path	Method	Description
Sandbox `https://api-test.switchpayments.com/v2/charges/types` Production `https://api.switchpayments.com/v2/charges/types`	GET	List the available charge types, meaning payment methods. This list includes all the fields that should be displayed on checkout and filled out by the customer.

Response Parameters

collectionArray

An array of JSON objects that contains all the charge types currently active.

idString

This is an unique identifier for the charge type.

payoutBoolean

Indicates whether the current charge type is designed to pay or receive funds.
true: the charge type is a payout.
false: the charge type is not a payout.

labelString

The designation that describes the charge type.

capture_on_creationBoolean

Indicates whether the current charge type is a capture on creation transaction flow. It defines whether or not a payment should be requested on a successful instrument creation.
true: the charge type captures funds on creation.
false: the charge type does not capture funds on creation.

schema_merchantJSON Schema Object

This field specifies the parameters to be completed on the merchant side. These are the parameters that should be included in instrument_params and cannot be overridden by the customer, such as enable3DS.

typeString

The data type included in this property.

propertiesJSON Object

A JSON Object documenting each of the properties that should be collected from the user for the payment method in question.

schemaJSON Schema Object

Documents the data that should be collected for this charge type. This data can vary between different payment methods. To better understand the different requirements for each provider check out Integration Resources.

titleString

The user interface identifier for the charge type, meaning payment method.

typeString

The data type included in this property.

requiredArray

List of mandatory fields the customer should fill out to proceed with the charge.

propertiesJSON Object

A JSON object documenting the available payment provider specific parameters and data types.

minimumNumber

The minimum value supported for this property. It applies when the data type is a number.

maximumNumber

The maximum value supported for this property. It applies when the data type is a number.

typeString

The data type of the property being collected.

titleString

The user interface identifier for the property being collected.

minLengthNumber

The minimum supported length for this property. It applies when the data type is a string.

maxLengthNumber

The maximum supported length for this property. It applies when the data type is a string.

ui_schemaJSON Schema Object

This JSON object contains the user interface information used to aid in rendering the required input collection forms. It is useful when using Dynamic Forms.

ui:placeholderString

Contains the placeholder text that should be added to the input of the property. This exemplifies to the user the required input.

ui:helpString

Contains helpful indications for the user regarding the property in question.

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

RESPONSE: HTTP 201
  {
    "collection": [
      "...",
      {
        "id": "card_onetime",
        "payout": false,
        "label": "Card One-Time",
        "capture_on_creation": true,
        "schema_merchant": {
          "type": "object",
          "properties": {
            "enabled3ds": {
              "type": "boolean"
            }
          }
        },
        "schema": {
          "title": "Credit/Debit Card",
          "type": "object",
          "required": ["name", "number", "expiration_month", "expiration_year", "cvv"],
          "properties": {
            "expiration_month": {
              "minimum": 1,
              "type": "number",
              "maximum": 12,
              "title": "Expiration Month"
            },
            "cvc": {
              "minLength": 3,
              "maxLength": 4,
              "type": "string",
              "title": "CVV"
            },
            "number": {
              "minLength": 14,
              "maxLength": 19,
              "type": "string",
              "title": "Card Number"
            },
            "expiration_year": {
              "type": "number",
              "title": "Expiration Year"
            },
            "name": {
              "minLength": 3,
              "maxLength": 255,
              "type": "string",
              "title": "Cardholder Name"
            }
          }
        },
        "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"
          }
        }
      },
      "..."
    ]
  }

POST `/v2/charges`

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

Request Parameters

charge_typeStringRequired

Payment method selected by the customer.

amountFloatRequired

Amount of the transaction in question.

currencyStringRequired

Currency used in this transaction.

metadataJSON Object

Any metadata that uniquely identifies this transaction in your system. This field is used to identify this transaction when handling events, searching for transactions on the Switch Dashboard, dynamically routing transactions or managing Risk.

events_urlString

HTTPS merchant server-side webhook where events will be handled.

redirect_urlString

HTTPS URL, or URL schemas when considering mobile apps, to send users back to. This field applies to payment methods that require customer redirection, such as Paypal or 3DS enabled credit cards.

instrument_paramsJSON Object

With this field the merchant can pass parameters which will be used when creating the instrument.

channelsArray

Indicates which channels you use for the transaction. In case it is empty the default Switch channel will be used.

REQUEST
  $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u accountId:privateKey -d '{
    "charge_type": "card_onetime",
    "amount": 42,
    "currency": "EUR",
    "metadata": {"orderId": "1337"},
    "events_url": "https://merchant.com/events",
    "redirect_url": "https://merchant.com/redirect",
    "instrument_params": {"descriptor": "D891220"},
    "channels": ["card_onetime_acapture"]
  }'

Response Parameters

idString

The charge ID that can be used once to create an instrument.

charge_typeString

Identifier of the charge type, or payment method.

charge_type_labelString

User-friendly identifier of the charge type, or payment method.

amountFloat

Amount set for the charge.

currencyString

The currency used in the charge.

events_urlString

HTTPS merchant server-side webhook where events will be handled.

redirect_urlString

HTTPS URL, or URL schemas when considering mobile apps, to send users back to. This field applies to payment methods that require customer redirection, such as Paypal or 3DS enabled credit cards.

metadataJSON Object

instrument_paramsJSON Object

With this field the merchant can pass parameters which will be used when creating the instrument.

channelsArray

Indicates which channels you use for the transaction. In case it is empty the default Switch channel will be used.

confirmedBoolean

Indicates if the created charge was confirmed by the merchant using their private key.
true: the charge was confirmed by the merchant using their private key.
false: the charge was not confirmed by the merchant using their private key.

instrument_paramsJSON Object

The instrument parameters used to create the charge.

events_urlString

Endpoint to which notifications of all the lifecycle events related to this charge will be sent

created_atString

The date when the charge was created.

expires_atDatetime

Stores the date and time when the charge element expires.

updated_atString

The date when the charge was last updated.

request_logJSON Object

Contains information on the origin of the request, such as country, ip_address, user_agent and the library_version.

externalBoolean

This boolean flag indicates if the current charge has been created in the Switch Platform or if it was incorporated via external sources.
true: the charge has been created by the Switch Platform.
false: the charge was created outside of the Switch Platform.

failure_codeString

For charge elements that failed to be created, this field will document the associated error code.

failure_descriptionString

Documents a user interface description of why this particular charge element failed to be created.

RESPONSE: HTTP 201
    {
        "id": "ceb69ab2eeb161ee6ed4906bff883dc1c82f3fb95f1859f1",
        "external_ids": null,
        "charge_type": "card_onetime",
        "charge_type_label": "Card One-Time",
        "amount": 42.0,
        "currency": "EUR",
        "events_url": "https://merchant.com/events",
        "redirect_url": "https://merchant.com/redirect",
        "metadata": {
            "orderId": "1337"
        },
        "instrument_params": {
            "descriptor": "D891220"
        },
        "failure_code": null,
        "failure_description": null,
        "channels": [
            {
                "id": "704d26ef06980411b178d5436294b8d99e443abc5b1ead14",
                "label": "card_onetime_acapture",
                "processor": "acapture"
            }
        ],
        "confirmed": true,
        "created_at": "2020-07-22T15:23:29.253599+00:00",
        "expires_at": null,
        "updated_at": "2020-07-22T15:23:29.253650+00:00",
        "request_log": {
            "ip_address": "149.90.219.7",
            "country": "PT",
            "library_version": null
        },
        "external": false
    }

It is not possible to create a charge without registering all the required fields. Tending to this error case, a list with all the invalid fields and the respective errors is returned.

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

Response Parameters

messageString

String with the error details. In this case: "Invalid parameters".

parametersJSON Object

A list with all the invalid fields and the respective errors.

RESPONSE: HTTP 400
  {
    "message": "Invalid parameters",
    "parameters": {
      "currency": [
        "This field is required."
      ],
      "events_url": [
        "This field is required."
      ]
    }
  }

It is possible to pass instrument parameters when creating a charge. For example, we can use the instrument_params in the charge to enable 3DS, as follows.

REQUEST
  $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u accountId:privateKey -d '{
    "charge_type": "card_onetime",
    "currency": "EUR",
    "amount": 10,
    "metadata": {"orderId":"837232"},
    "events_url": "https://merchant.com/events",
    "instrument_params": {"enable3ds": true}
  }'

RESPONSE: HTTP 200
  {
    "id": "35ed95bfb772b94c4e59f91fcbef0f5618d46e3d5b2b7da5",
    "charge_type": "card_onetime",
    "amount": 10,
    "currency": "EUR",
    "confirmed": true,
    "instrument_params": {
      "enable3ds": true
    },
    "events_url": "https://merchant.com/events",
    "expires_at": "2018-06-21T10:32:49.241268+00:00",
    "channels": null,
    "charge_type_label": "Card One-Time",
    "redirect_url": "",
    "metadata": {
      "orderId": "837232"
    },
    "external_ids": null,
    "request_log": {
      "country": null,
      "ip_address": "100.10.10.10",
      "user_agent": "curl/7.54.0",
      "library_version": null
    },
    "created_at": "2018-06-21T10:27:49.241769+00:00",
    "updated_at": "2018-06-21T10:27:49.241800+00:00"
  }

It is also possible to choose what channel you want to use for the transaction, using for that the channels field in the charge.

REQUEST
  $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u accountId:privateKey -d '{
    "charge_type": "card_onetime",
    "currency": "EUR",
    "amount": 10,
    "metadata": {"orderId":"837232"},
    "events_url": "https://merchant.com/events",
    "channels": ["card_onetime_checkout"]
  }'

Instrument

instrument is the object used to initiate the transfer of funds. Instruments come in many shapes and sizes, they are collections of the authentication parameters for any given payment method. You should watch out for fingerprint and status when evaluating instruments. Authentication fields for a card can include parameters like cardholder_name, PAN, CVV and expiry_date, whereas payments methods like PayPal would only require a redirection_url. Each instrument generates one or more payment objects.

This following request examples describe a card_onetime instrument. Each charge type has its own required fields which you should be mindful of that when setting up your requests. For more information on this topic, access Integration Resources..

POST `/v2/instruments`

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

Request Parameters

chargeStringRequired

The identifier of the charge associated with this payment that was previously created.

nameStringRequired

The cardholder name.

numberIntegerRequired

The credit card number.

expiration_monthIntegerRequired

Expiration month for the card being used.

expiration_yearIntegerRequired

Expiration year for the card being used. Mind this value in your tests, past dates can generate errors.

cvcIntegerRequired

The card verification code.

REQUEST
  $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u publicKey -d '{
          "charge": "a325e88948799260d9d8319a3ddb79ff2f74bbf35f198b30",
          "name": "John Doe",
          "number": "4111111111111111",
          "expiration_month": 12,
          "expiration_year": 2030,
          "cvc": "007"
      }'

Response Parameters

idString

The ID that uniquely identifies the instrument element for this transaction.

external_idsString

A JSON Object documenting any external ID that the payment provider has related to the current instrument, if applicable.

successString

This boolean flag indicates whether the current Instrument has been successfully created.
true: the instrument has been successfully created.
false: the instrument has failed to be created.

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: indicates that additional information is still necessary proceed forward.

failure_codeString

For instrument elements that failed to be created, this field will document the associated error code.

failure_descriptionString

Documents a user interface description of why this particular instrument element failed to be created.

parametersJSON Object

Contains the parameters that identify the customer and/or the payment instrument.

fingerprintString

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

referenceString

Only applicable to payment methods that require the customer to complete the transaction asynchronously outside of the Switch Platform. Documents the information required to the customer. The specific schema of this object will depend on the payment method being used.

responseJSON Object

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

redirectJSON Object

Used for payment methods that require redirection, documents the information required to direct the user to the page where the transaction can be completed.
url: the URL to where the user should be redirected.
method: the HTTP method that should be used when performing the URL call.
params: the parameters that should be passed along with the URL call.

created_atDatetime

Contains the date and time when the instrument element was originally created.

updated_atDatetime

Stores the date and time when the instrument element was last updated.

request_logJSON Object

Stores information about the location and browser used to create the instrument element, such as the country of the IP address or the user agent.

externalBoolean

This boolean flag indicates if the current instrument has been created in the Switch Platform or if it was injected via external sources.
true: the instrument has been created by the Switch Platform.
false: the instrument was created outside of the Switch Platform.

recurringBoolean

This boolean flag indicates if the current instrument is classified as recurring.
true: it is a recurring instrument.
false: it is not a recurring instrument.

capture_on_creationBoolean

This boolean flag indicates if the current instrument is classified as captured on creation.
true: capture on creation instrument, the payment is automatically captured on the instrument authorization.
false: not a capture on creation instrument.

channelJSON Object

Documents the properties of the Switch channel that was used to process this given instrument element.
id: identification of the channel being used.
label: user-friendly designation of the channel being used.
processor: provider associated with the transactions in this channel.

usedBoolean

Indicates whether a successful payment was already completed with the instrument in question.
true: this instrument was already used in a successful payment.
false: this instrument was not previously applied to a successful payment.

last_paymentJSON Object

Contains details on the last payment performed with the instrument in question.

chargeJSON Object

Describes the charge element that was used to create this instrument.

RESPONSE: HTTP 201
    {
      "id": "e866b0f517e92bd392183e53450dd6bd87e8cdc35f199c3c",
      "external_ids": {
          "processor": "8ac7a49f737620a201737c0a4bfb669c",
          "descriptor": "3750.0784.9102 Switch CC"
      },
      "success": true,
      "status": "authorized",
      "failure_code": null,
      "failure_description": null,
      "params": {
          "name": "John doe",
          "expiration_month": 12,
          "expiration_year": 2030,
          "descriptor": "D891220",
          "card_bin": "411111",
          "card_last_4_digits": "1111",
          "bin": "411111",
          "last_4_digits": "1111",
          "card_bank": "JPMORGAN CHASE BANK, N.A.",
          "card_brand": "VISA",
          "card_country": "US",
          "card_account_type": "CREDIT",
          "bank": "JPMORGAN CHASE BANK, N.A.",
          "bank_phone": "1-212-270-6000",
          "brand": "VISA",
          "country": "UNITED STATES",
          "country_isoa2": "US",
          "country_isoa3": "USA",
          "country_isonumber": "840",
          "type": "CREDIT"
      },
      "fingerprint": "947cc6e0e908f1e7c2670a4e44a8194397966738d0fae5640f9889f2f1fbc16eef7dd19dc4603a5632d69087e6969ea5de876bca6db687b922ac999a6fddfb56",
      "reference": null,
      "response": null,
      "redirect": null,
      "created_at": "2020-07-23T14:18:36.596701+00:00",
      "updated_at": "2020-07-23T14:18:36.596722+00:00",
      "request_log": {
          "ip_address": "149.90.219.7",
          "country": "PT",
          "user_agent": "PostmanRuntime/7.26.2",
          "library_version": null
      },
      "external": false,
      "recurring": false,
      "capture_on_creation": true,
      "channel": {
          "id": "704d26ef06980411b178d5436294b8d99e443abc5b1ead14",
          "label": "card_onetime_acapture",
          "processor": "acapture"
      },
      "used": true,
      "last_payment": {
          "id": "2dfba90fcc304376701a2691677d1e68713bb8075f199c3c",
          "success": true,
          "status": "success"
      },
      "charge": {
          "id": "a325e88948799260d9d8319a3ddb79ff2f74bbf35f198b30",
          "charge_type": "card_onetime",
          "charge_type_label": "Card One-Time",
          "amount": 42.0,
          "currency": "EUR",
          "created_at": "2020-07-23T13:05:52.777328+00:00"
      }
  }

For payment methods that require a reference JSON Object, such as Multibanco, the field will contain the structure below. Please note that this information should be shown to the customer.


  {
    "reference": {
      "fields": [
        {"field": "entity", "value": "815412", "label": "Entity"},
        {"field": "reference", "value": "412523632", "label": "Reference"},
        {"field": "value", "value": "10", "label": "Value"}
      ]
    }
  }

GET `/v2/instruments/{id}`

Merchants are able to make GET/v2/instruments requests with both private and public credentials. The response is different for either case, as shown in the following examples.

Path	Method	Description
Sandbox `https://api-test.switchpayments.com/v2/instruments/{id}` Production `https://api.switchpayments.com/v2/instruments/{id}`	GET	Gets the details of an `instrument` element using its ID.

REQUEST ACCOUNTID:PRIVATEKEY
    $ curl -vX GET https://api-test.switchpayments.com/v2/instruments/{id}
        -u accountId:privateKey

RESPONSE: HTTP 200
    {
        "id": "ca4cb4177f8f9b18726f3605f25c3fa5412a8f2e5f157233",
        "external_ids": {
            "processor": "8ac7a4a0736acff601736bc61b003fbf",
            "descriptor": "4645.9162.8814 Switch CC"
        },
        "success": true,
        "status": "authorized",
        "failure_code": null,
        "failure_description": null,
        "params": {
            "name": "John Doe",
            "expiration_month": 12,
            "expiration_year": 2020,
            "card_bin": "411111",
            "card_last_4_digits": "1111",
            "bin": "411111",
            "last_4_digits": "1111",
            "card_bank": "JPMORGAN CHASE BANK, N.A.",
            "card_brand": "VISA",
            "card_country": "US",
            "card_account_type": "CREDIT",
            "bank": "JPMORGAN CHASE BANK, N.A.",
            "bank_phone": "1-212-270-6000",
            "brand": "VISA",
            "country": "UNITED STATES",
            "country_isoa2": "US",
            "country_isoa3": "USA",
            "country_isonumber": "840",
            "type": "CREDIT"
        },
        "fingerprint": "947cc6e0e908f1e7c2670a4e44a8194397966738d0fae5640f9889f2f1fbc16eef7dd19dc4603a5632d69087e6969ea5de876bca6db687b922ac999a6fddfb56",
        "reference": null,
        "response": null,
        "redirect": null,
        "created_at": "2020-07-20T10:30:12.132238+00:00",
        "updated_at": "2020-07-20T10:30:12.132259+00:00",
        "request_log": {
            "country": "PT",
            "ip_address": "149.90.219.7",
            "user_agent": "PostmanRuntime/7.26.1",
            "library_version": null
        },
        "external": false,
        "recurring": false,
        "capture_on_creation": true,
        "channel": {
            "id": "9a48d37466f9323dc8c305fbf082fe5b80ca75b95af9ba98",
            "label": "wirecard",
            "processor": "acapture"
        },
        "used": true,
        "last_payment": {
            "id": "d1d44207a96f9c10c6ab7a6e43309937045453c65f157234",
            "success": true,
            "status": "success"
        },
        "charge": {
            "id": "3307721a72908e1a7a68d81ea9e08b758b63a87c5f157224",
            "charge_type": "card_onetime",
            "charge_type_label": "Card One-Time",
            "amount": 100.0,
            "currency": "EUR",
            "created_at": "2020-07-20T10:29:56.768942+00:00",
            "metadata": {
                "name": "Maria"
            }
        }
    }

Response Parameters

idString

The ID that uniquely identifies the instrument element for this transaction.

external_idsString

A JSON Object documenting any external ID that the payment provider has related to the current instrument, if applicable.

successString

This boolean flag indicates whether the current Instrument has been successfully created.
true: the instrument has been successfully created.
false: the instrument has failed to be created.

statusString

failure_codeString

For instrument elements that failed to be created, this field will document the associated error code.

failure_descriptionString

Documents a user interface description of why this particular instrument element failed to be created.

parametersJSON Object

Contains the parameters that identify the customer and/or the payment instrument.

fingerprintString

A unique, one-way hash fingerprint of the instrument, which can be leveraged for risk prevention purposes.

referenceString

responseJSON Object

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

redirectJSON Object

created_atDatetime

Contains the date and time when the instrument element was originally created. Consider ISO 8601.

updated_atDatetime

Stores the date and time when the instrument element was last updated. Consider ISO 8601.

request_logJSON Object

Stores information about the location and browser used to create the instrument element, such as the country of the IP address or the user agent.

externalBoolean

recurringBoolean

This boolean flag indicates if the current instrument is classified as recurring.
true: it is a recurring instrument.
false: it is not a recurring instrument.

capture_on_creationBoolean

channelJSON Object

usedBoolean

last_paymentJSON Object

Contains details on the last payment performed with the instrument in question.

chargeJSON Object

Describes the charge element that was used to create this instrument.

REQUEST PUBLICKEY
    $ curl -vX GET https://api-test.switchpayments.com/v2/instruments/{id}
        -u publicKey

RESPONSE: HTTP 200
    {
      "id": "ca4cb4177f8f9b18726f3605f25c3fa5412a8f2e5f157233",
      "success": true,
      "status": "authorized",
      "used": true,
      "last_payment": {
          "id": "d1d44207a96f9c10c6ab7a6e43309937045453c65f157234",
          "success": true,
          "status": "success"
      },
      "created_at": "2020-07-20T10:30:12.132238+00:00",
      "updated_at": "2020-07-20T10:30:12.132259+00:00"
  }

Response Parameters

idString

The ID that uniquely identifies the instrument element for this transaction.

successString

This boolean flag indicates whether the current Instrument has been successfully created.
true: the instrument has been successfully created.
false: the instrument has failed to be created.

statusString

usedBoolean

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

last_paymentJSON Object

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

created_atDate

Contains the date and time when the instrument element was originally created. Consider (ISO 8601.

updated_atDate

Stores the date and time when the instrument element was last updated. Consider ISO 8601.

For payment methods that require a reference JSON object, such as Multibanco, the payload will contain the structure shown below.


  {
    "reference": {
      "fields": [
        {"field": "entity", "value": "815412", "label": "Entity"},
        {"field": "reference", "value": "412523632", "label": "Reference"},
        {"field": "value", "value": "10", "label": "Value"}
      ]
    }
  }

Payment

Verifying the status of payments is essential to any business. A payment is a transaction authorization from a provider. Payments can be synchronous or asynchronous, payins or payouts, redirection-based, pre-payments or post-payments, one-time or recurring. The payment object contains the technical information returned by the provider when processing your payments. Every payment comes with a charge_id and instrument_id, completing the transaction cycle.

POST `/v2/payments`

Path	Method	Description
Sandbox `https://api-test.switchpayments.com/v2/payments` Production `https://api.switchpayments.com/v2/payments`	POST	Creates a new `payment` for a given transaction.

Request Parameters

instrumentStringRequired

The unique identifier for the instrument element that was previously created for this transaction.

currencyStringRequired

ISO 4217 code that indicates the currency that will be used in the transaction.

amountFloatRequired

The amount that should be captured from the customer.

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. This field will be used to identify this transaction when handling events, searching for transactions on the Dashboard, dynamically routing transactions or managing Risk.

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

Response Parameters

idString

The ID that uniquely identifies the newly created payment element for this transaction.

amountFloat

The amount that was charged to the customer.

currencyString

ISO 4217 code. It indicates the currency that was used by the transaction.

externalBoolean

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

metadataBoolean

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

successBoolean

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

responseJSON Object

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

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.

refundableBoolean

Indicates whether the current payment can be refunded back to the customer, as some payment methods do not support this operation.
true: the payment can be refunded back to the customer.
false: the payment cannot be refunded back to the customer.

failure_descriptionString

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

refundsArray

Stores the properties of the refund elements related to this payment.

instrumentJSON object

This JSON Object stores the properties of the instrument element related to this payment, as described in the previous sections.

chargeJSON object

This JSON Object stores the properties of the charge element related to this payment, as described in the previous sections.

external_idsJSON Object

Documents the provider ID for the current payment, if available.

request_logJSON Object

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

created_atDatetime

Indicates the date and time when the current payment element was created (ISO 8601).

updated_atDatetime

Documents the date and time when the last update was performed to the current payment (ISO 8601).

RESPONSE
  {
    "id": "ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27",
    "amount": 42,
    "currency": "EUR",
    "description": "",
    "external": false,
    "metadata": {},
    "success": true,
    "response": {
      "eci_code": "05"
    },
    "params": null,
    "refundable": true,
    "failure_description": null,
    "refunds": [],
    "instrument": {
      "id": "0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc",
      "channel": {
        "processor": "checkout",
        "id": "85a557e4fdb6c8806f413bc75fabab162828e4f95b8e6390",
        "label": "card_onetime_checkout"
      }
    },
    "charge": {
      "charge_type": "card_onetime",
      "charge_type_label": "Card One-Time",
      "id": "ceb69ab2eeb161ee6ed4906bff883dc1c82f3fb95f1859f1",
      "metadata": {
        "orderId": "837232"
      }
    },
    "external_ids": {
      "transaction_id_trunc": "918dd9382a17be5d060f9a8dd15674",
      "processor": "8a8294496421b8d30164222227f17687",
      "transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"
    },
    "request_log": {
      "country": "PT",
      "ip_address": "100.10.10.10",
      "user_agent": "curl/7.54.0",
      "library_version": null
    },
    "created_at": "2018-07-05T14:46:00.040018+00:00",
    "updated_at": "2018-07-05T14:46:00.040037+00:00"
  }

Reversal

A reversal is a transaction cancelation previous to clearing. The reversal object translates both reversal and void processes. A void refers to a pre-authorization cancelation.

Reversals stop the payment process in an earlier stage, before refunds or disputes become necessary. This translates into less hassle for your customer and smaller fees for your business. Reversals can be applied to instruments, payments, or refunds.

Keep in Mind

The correct way of performing this operation is by creating a reversal and not by deleting a payment, instrument, or refund.

POST `/v2/reversals`

Path	Method	Description
Sandbox `https://api-test.switchpayments.com/v2/reversals` Production `https://api.switchpayments.com/v2/reversals`	POST	Applies a `reversal` on the `instrument`, `payment`, or `refund` element, thus canceling the transaction authorization. Used in auth-capture or recurring transaction flows.

Request Parameter

object_typeStringRequired

Indicates the object type intended for reversal. Currently you are able to apply reversal to instrument, payments, and refund. For a list of updated values please contact our Support Team.

object_idFloatRequired

The ID that uniquely identifies the element to participate in the reversal.

REQUEST
    $ curl -vX POST https://api-test.switchpayments.com/v2/reversals -u accountId:privateKey -d '{
        "object_type": "instrument",
        "object_id": "ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27"
      }'

Response Parameters

reversalJSON Object

A JSON object containing the details of the reversal element that was created as a result of the object being voided.

idString

The ID that uniquely identifies the reversal element that was created to void the instrument.

external_idsJSON Object

A JSON Object documenting any external ID that the payment provider has related to the current reversal, if applicable.

object_idString

The unique ID of the object to which the void pertains to, in this case the instrument element.

object_typeString

The type of object to which the void pertains to, in this case the instrument element.

amountFloat

The amount that was voided.

initiated_byString

Indicates the transaction entity that requested the reversal. Required since a reversal may be requested by the merchant or the provider.

statusString

Documents the execution status for the void action.
success: the instrument was successfully voided.
error: the instrument could not be voided.
pending: The instrument is in the process of being voided, used for providers that have an asynchronous process.

successBoolean

This boolean flag documents if the void operation has been completed successfully.
true: the instrument was successfully voided.
false: the instrument has not yet been voided.

failure_codeJSON Object

For reversal elements that failed to be created, this field will document the associated error code.

failure_descriptionJSON Object

Description of why this particular reversal element failed to be created.

request_logJSON Object

Stores information about the location and browser used to create the reversal element, such as the country of the IP address or the user agent.

externalJSON Object

This boolean flag indicates if the current Reversal element has been created in the Switch Platform or was later injected via external sources.
true: the reversal has been created by the Switch Platform.
false: the reversal was created outside of the Switch Platform.

created_atJSON Object

Contains the date and time when the reversal element was originally created (ISO 8601).

RESPONSE
  {
     "reversal": {
         "id": "3f21bd06113cc34a27c50633491886091da99ea45cf7ca1a",
         "external_ids": {
             "processor": "8ac7a4a16b277c82016b27ed781065ed"
         },
         "object_id": "846ed631e9ebb72b867d38bd6d3f39a5bc9cd2025cf7c9fb",
         "object_type": "instrument",
         "amount": 10,
         "initiated_by": "merchant",
         "status": "success",
         "success": true,
         "failure_code": null,
         "failure_description": null,
         "request_log": {
             "country": null,
             "ip_address": "172.22.0.1",
             "user_agent": "PostmanRuntime/7.11.0",
             "library_version": null
         },
         "external": false,
         "created_at": "2019-06-05T13:56:43.586212+00:00"
     }
  }

Refund

In a refund the payment has already been settled, but you need to return the money to the customer, this means that with a refund you complete the transaction in reverse. When handling refunds, you should be aware of which payment needs to be refunded, the amount of said refund and the appropriate justification for it.

POST `/v2/refunds`

Path	Method	Description
Sandbox `https://api-test.switchpayments.com/v2/refunds` Production `https://api.switchpayments.com/v2/refunds`	POST	Creates a new `refund` for a given payment.

Request Parameter

paymentStringRequired

The identifier of the payment previously created.

amountFloatRequired

The amount to be refunded. This value can account for a partial refund corresponding to only a portion of the total amount. Yet, it cannot exceed the total amount of the payment.

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

Response Parameters

idString

Unique identifier for the refund.

amountFloat

The refund amount. It can correspond to a partial refund or the total amount set in the payment.

created_atDatetime

The date and time when the refund was created (ISO 8601).

externalBoolean

This boolean flag indicates if the current charge has been created in the Switch platform or if it was incorporated via external sources.
true: the charge has been created by the Switch platform.
false: the charge was created outside of the Switch Platform.

failure_codeString

If the refund was not successful, this field contains the respective failure code.

failure_descriptionString

If the refund was not successful, this field contains details about the failure.

paymentJSON Object

Contains a summary of the payment object related to this refund.

request_logJSON Object

Contains information on the origin of the request, such as country, ip_address, user_agent and the library_version.

successBoolean

Flag indicating whether the refund was successfully created or not.
true: the refund was successfully created.
false: the refund was not created.

instrumentJSON Object

This JSON Object stores the properties of the instrument element related to this payment, as described in the previous sections.

chargeJSON Object

This JSON Object stores the properties of the charge element related to this payment, as described in the previous sections.

RESPONSE HTTP 201
    {
            "id": "d243e39cdf7f55f6a185235ac8ae8d67d469b29c5b44a1f0",
            "success": true,
            "status": "success",
            "amount": 42,
            "created_at": "2018-07-10T12:09:21.227579+00:00",
            "description": "Refund description",
            "external": false,
            "external_ids": {
              "descriptor": "0957.6372.2914 Switch CC",
              "processor": "8a829449646618a10164841895d1506c",
              "transaction_id": "7b6dfed71377d4065d873342422362121600fcef5b2bb2e9",
              "transaction_id_trunc": "7b6dfed71377d4065d873342422362"
            },
            "failure_code": null,
            "failure_description": null,
            "payment": {
              "id": "ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27"
            },
            "request_log": {
              "country": "PT",
              "ip_address": "11.123.1.23",
              "library_version": null,
              "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36"
            },
       "instrument": {
           "id": "0370cf3fa5f2d8b541d18bc6e39e28b01ae7aa0f5f2291f0",
           "channel": {
               "id": "9c62fb17a095f6dc32f3f36ea289f8a9473afcb95b1ead14",
               "label": "card_onetime_acapture",
               "processor": "acapture"
           }
       },
       "charge": {
           "id": "8f3e835780450782d228f395a12624f2fe819ed55f2291ec",
           "charge_type": "card_onetime",
           "charge_type_label": "Card One-Time",
           "metadata": {
               "order_id": "1235f4e5456d4e56f3",
           }
       }
    }

Next Steps

Understand how you can use settlements and sources to watch over your transactions and how to access agreements and disputes. Learn more about Reconciliation.

Processing

Every payment flow, one integration.

Create charge, instrument, and payment

Refund and reversal

Charge

Instrument

Payment

Reversal

Refund

Channels

Charge

GET /v2/charges/types

Response Parameters

POST /v2/charges

Request Parameters

Response Parameters

Check out the following use cases

Response Parameters

Instrument

POST /v2/instruments

Request Parameters

Response Parameters

Check out the following use case

GET /v2/instruments/{id}

Response Parameters

Response Parameters

Check out the following use case

Payment

POST /v2/payments

Request Parameters

Response Parameters

Reversal

Keep in Mind

POST /v2/reversals

Request Parameter

Response Parameters

Refund

POST /v2/refunds

Request Parameter

Response Parameters

Next Steps

GET `/v2/charges/types`

POST `/v2/charges`

POST `/v2/instruments`

GET `/v2/instruments/{id}`

POST `/v2/payments`

POST `/v2/reversals`

POST `/v2/refunds`