External Sources Service

Transactions that have been processed outside Switch's Processing API can be imported to the platform using the Sources service. They will not be forwarded to any processor, but will still be available in other services, such as the Transactions, Risk, Analytics, Settlements and Reporting.

Charges

The available operations for the charge resource are:

POST /v1/sources/charges

Request Parameter

charge_typeStringRequired

Payment method selected by the customer


amountFloatRequired

Transaction amount


currencyStringRequired

Transaction currency


created_atStringRequired

The date when the charge was created (ISO 8601 format)


operationJSON ObjectRequired

Include metadata keyword (must be JSON object) with some external operation metadata from the processor


channelsArray

Indicates which channels you want to use for the transaction


metadataJSON Object

Any metadata that uniquely identifies this transaction in your system. This field will be used to identify this transaction when handling events, searching for transactions on the 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 for mobile apps) to send users back to, for payment methods that require customer redirection, e.g. Paypal or Credit Cards with 3D-secure


instrument_paramsJSON Object

The merchant can pass parameters which will be used when creating the instrument


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version. (Defaults to the one who made the request)

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/sources/charges?merchant_id=merchantID -u accountId:APIKey -d '{
"charge_type": "card_onetime",
"amount": 42,
"currency": "EUR",
"created_at": "2018-10-16T15:15:34.694149+00:00",
"operation": {"metadata": {"transaction_id": "123123123"}},
"channels": ["card_onetime_checkout”],
"metadata": {"orderId": "1337"},
"events_url": "https://merchant.com/events",
"redirect_url": "https://merchant.com/redirect",
"instrument_params": {"descriptor": "D891220"},
"request_log: {"country": null, "ip_address": "100.10.10.10", "user_agent": "curl/7.54.0", "library_version": null}
}'
Result Parameter

idString

The charge id that can be used once to create an Instrument


amountFloat

Maximum amount set for the charge


currencyString

The currency of the charge


charge_typeString

Identifier of the charge type


charge_type_labelString

The charge pretty name


confirmedBoolean

Indicates if the created charge was confirmed by the Merchant using their private key


created_atString

The date when the charge was created


updated_atString

The date when the charge suffered some update


externalBoolean

Indicates if the created charge was created as an external source


metadataJSON Object

Provided charge metadata


external_idsJSON Object

Processor IDs of the charge


redirect_urlString

Defined redirect url


instrument_paramsJSON Object

The instrument parameters used to create the charge


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version


channelsArray

Channels to be used in the transaction

RESULT: HTTP 201
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"amount": 42,
"currency": "EUR",
"charge_type": "card_onetime",
"charge_type_label": "Card One-Time",
"confirmed": true,
"created_at": "2018-10-16T15:15:34.694149+00:00",
"updated_at": "2018-10-16T15:15:34.694149+00:00",
"external": true,
"metadata": {
"orderId": "1337"
},
"events_url": "https://merchant.com/events",
"redirect_url": "https://merchant.com/redirect",
"instrument_params": {
"descriptor": "D891220"
},
"external_ids": null,
"request_log": {
"country": null,
"ip_address": "100.10.10.10",
"user_agent": "curl/7.54.0",
"library_version": null
},
"channels": [{
"processor": "checkout",
"id": "85a557e4fdb6c8806f413bc75fabab162828e4f95b8e6390",
"label": "card_onetime_checkout"
}]
}

Create charge without required fields

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/sources/charges?merchant_id=merchantID -u accountId:APIKey -d '{
"charge_type": "card_onetime",
"amount": 42,
"created_at": "2018-10-16T15:15:34.694149+00:00"
}'
Result Parameter

messageString

String with the error details, in this case: "Invalid parameters"


parametersJSON Object

A list with all the invalid fields and the respective errors

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

PATCH /v1/sources/charges/<id>

You can update some charge fields by sending a PATCH request with a payload of any combination of the previously mentioned parameters.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/sources/charges/756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954?merchant_id=merchantID -u accountId:APIKey -d '{
"amount": 42
}'

Instruments

The available operations for the instrument resource are:

POST /v1/sources/instruments

Request Parameter

chargeStringRequired

The identifier of the charge that was previously created


created_atStringRequired

The date when the charge was created (ISO 8601 format)


operationJSON ObjectRequired

Any operation metadata required to handle the transaction on the processor side


paramsJSON Object

The sanitized instrument parameters


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version. (Defaults to the one who made the request)

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/sources/instruments?merchant_id=merchantID -u accountId:APIKey -d '{
"charge": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"created_at": "2018-10-16T15:15:34.694149+00:00",
"operation": {"metadata": {"transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"}},
"request_log": {"country": null, "ip_address": "100.10.10.10", "user_agent": "curl/7.54.0", "library_version": null}
}'
Result Parameter

idString

The instrument id that can be used to create a Payment


statusString

Current status of the instrument. It could be Pending, Invalid or Authorized


successBoolean

Flag indicating whether the instrument was successfully created


usedBoolean

Flag indicating whether the instrument has already been used


externalBoolean

Indicates if the created charge was created as an external source


chargeJSON Object

Details about the charge


last_paymentJSON Object

It's a reference for the last payment of the instrument. If exists, the object has the following keys: id (string) and success (boolean)


created_atString

The date when the instrument was created


updated_atString

The date when the instrument suffered some update


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version


external_idsJSON Object

Useful external ids (e.g. IDs from the processing channel)


redirectJSON Object

Contains information from the provider on how to redirect the merchant


paramsJSON Object

Includes the instrument parameters concatenated with the instrument_params from the corresponding charge


channelJSON Object

Channel used to create the instrument


failure_descriptionString

If the instrument was not successful there may be details in this field about the reasons for the error (e.g. from the processor)

RESULT: HTTP 200
{
"id": "0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc",
"status": "pending",
"success": true,
"used": false,
"external": true,
"charge": {
"charge_type": "card_onetime",
"currency": "EUR",
"created_at": "2018-06-18T10:28:36.358233+00:00",
"charge_type_label": "Card One-Time",
"amount": 10,
"id": "35ed95bfb772b94c4e59f91fcbef0f5618d46e3d5b2b7da5"
},
"last_payment": null,
"created_at": "2018-10-16T15:15:34.694149+00:00",
"updated_at": "2018-06-21T11:37:01.694168+00:00",
"request_log": {
"country": null,
"ip_address": "100.10.10.10",
"user_agent": "curl/7.54.0",
"library_version": null
},
"external_ids": {
"processor": "8a8294496421b8d30164222227f17687",
"transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"
},
"redirect": {
"url": "https://test.ppipe.net/connectors/demo/simulator.link",
"method": null,
"parameters": [
{
"name": "MD",
"value": "8a8294496421b8d301642222287d768e"
},
{
"name": "PaReq",
"value": "IT8ubu+5z4YupUCOEHKsbiPep8UzIAcPKJEjpwGlzD8#KioqKioqKioqKioqMTExMSMxMC4wMCBFVVIj"
},
{
"name": "TermUrl",
"value": "https://test.ppipe.net/connectors/asyncresponse_simulator;jsessionid=9DBF6D37DA9B12E4B23A70F2452A8021.sbg-vm-con02?asyncsource=THREEDSECURE&ndcid=8a82941751c365120151c4a473fa04bf_830642b94a9040a3a08463b9414f0396"
},
{
"name": "connector",
"value": "THREEDSECURE"
}
]
},
"params": {
"descriptor": "D891220"
},
"channel": {
"processor": "checkout",
"id": "85a557e4fdb6c8806f413bc75fabab162828e4f95b8e6390",
"label": "card_onetime_checkout"
},
"failure_description": null
}

PATCH /v1/sources/instruments/<id>

You can update some instrument fields by sending a PATCH request with a payload of any combination of the previously mentioned parameters.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/sources/instruments/0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc?merchant_id=merchantID -u accountId:APIKey -d '{
"status": "authorized"
}'

Payments

POST /v1/sources/payments

Request Parameter

instrumentStringRequired

The identifier of the instrument that was previously created


amountFloatRequired

Transaction amount


currencyStringRequired

Transaction currency


created_atStringRequired

The date when the charge was created (ISO 8601 format)


operationJSON ObjectRequired

Any operation metadata required to handle the transaction on the processor side


descriptionString

Transaction description


metadataJSON Object

Any metadata that uniquely identifies this transaction in your system. This field will be used to identify this transaction when handling events, searching for transactions on the dashboard, dynamically routing transactions or managing risk


paramsJSON Object

The sanitized payment parameters


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version. (Defaults to the one who made the request)

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/sources/payments?merchant_id=merchantID -u accountId:APIKey -d '{
"instrument": "0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc",
"amount": 10,
"currency": "EUR",
"created_at": "2018-10-16T15:15:34.694149+00:00",
"operation": {"metadata": {"transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"}},
"description": "Payment description",
"metadata": {"orderId": "123"},
"request_log": {"country": null, "ip_address": "127.0.0.1", "user_agent": "curl/7.54.0", "library_version": null}
}'
Result Parameter

idString

Unique identifier of the payment


amountFloat

The payment amount


currencyString

The currency of the payment


descriptionString

Transaction description


created_atString

The date when the payment was created


updated_atString

Last date when the payment suffered an update


external_idsJSON Object

Useful external ids (e.g. IDs from the processing channel)


successBoolean

Flag indicating whether the payment was successfully created


externalBoolean

Indicates if the created charge was created as an external source


chargeJSON Object

Contains a trimmed object of the related charge: id, charge_type, charge_type_label, metadata


instrumentJSON Object

Contains a trimmed object of the related instrument: id, channel


refundsArray

A list that contains all the refunds objects related to the payment


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version


paramsJSON Object

The payment parameters


refundableBoolean

Defines whether or not the payment allows refunds


metadataJSON Object

Any metadata that uniquely identifies this transaction in your system. This field will be used to identify this transaction when handling events, searching for transactions on the dashboard, dynamically routing transactions or managing risk


failure_descriptionString

If the payment is not successful, this field has details about the failure

RESULT
{
"id": "ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27",
"amount": 42,
"currency": "EUR",
"description": "Payment description",
"created_at": "2018-10-16T15:15:34.694149+00:00",
"updated_at": "2018-10-16T15:15:34.694149+00:00",
"external_ids": {
"transaction_id_trunc": "918dd9382a17be5d060f9a8dd15674",
"processor": "8a8294496421b8d30164222227f17687",
"transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"
},
"success": true,
"external": true,
"charge": {
"charge_type": "card_onetime",
"charge_type_label": "Card One-Time",
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"metadata": {
"orderId": "837232"
}
},
"instrument": {
"id": "0d0e51462ef62787dcb711f3c7ec42d086a172f85b2b8ddc",
"channel": {
"processor": "checkout",
"id": "85a557e4fdb6c8806f413bc75fabab162828e4f95b8e6390",
"label": "card_onetime_checkout"
}
},
"refunds": [],
"request_log": {
"country": null,
"ip_address": "127.0.0.1",
"user_agent": "curl/7.54.0",
"library_version": null
},
"params": null,
"refundable": false,
"metadata": {"orderId": "123"},
"failure_description": null
}

PATCH /v1/sources/payments/<id>

You can update some payment fields by sending a PATCH request with a payload of any combination of the previously mentioned parameters.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/sources/payments/ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27?merchant_id=merchantID -u accountId:APIKey -d '{
"amount": 50
}'

Refunds

POST /v1/sources/refunds

Request Parameter

paymentStringRequired

The identifier of the payment that was previously created


amountFloatRequired

The amount to be refunded (can be partial but can not exceed the total amount of the payment)


created_atStringRequired

The date when the charge was created (ISO 8601 format)


operationJSON ObjectRequired

Any operation metadata required to handle the transaction on the processor side


descriptionString

Transaction description


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version. (Defaults to the one who made the request)

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/sources/refunds?merchant_id=merchantID -u accountId:APIKey -d '{
"payment": "ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27",
"amount": 10,
"created_at": "2018-10-16T15:15:34.694149+00:00",
"operation": {"metadata": {"transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"}},
"description": "Unapplied coupon",
"request_log": {"country": null, "ip_address": "127.0.0.1", "user_agent": "curl/7.54.0", "library_version": null}
}'
Result Parameter

idString

Unique identifier of the payment


amountFloat

The refund amount (must not exceed the payment amount)


successBoolean

Flag indicating whether the refund was successfully created


externalBoolean

Indicates if the created charge was created as an external source


descriptionString

Transaction description


created_atString

The date when the payment was created


paymentJSON Object

Contains a trimmed object of the related payment: id


request_logJSON Object

Contains information on the origin of the request: The country, ip_address, user_agent and the library_version


external_idsJSON Object

Useful external ids (e.g. IDs from the processing channel)


failure_descriptionString

If the refund is not successful, this field has details about the failure

RESULT
{
"id": "2d017c99745a15ddeda9ba0e35d8e1e26d3b512a5bc5d259",
"amount": 1.0,
"success": true,
"description": "Unapplied coupon",
"created_at": "2018-10-16T15:15:34.694149+00:00",
"payment": {
"id": "ed9fdf723c40fada03b6ce783beb182376a85c735b3e2f27"
},
"request_log": {
"country": null,
"ip_address": "127.0.0.1",
"user_agent": "curl/7.54.0",
"library_version": null
},
"external_ids": {
"transaction_id_trunc": "918dd9382a17be5d060f9a8dd15674",
"processor": "8a8294496421b8d30164222227f17687",
"transaction_id": "918dd9382a17be5d060f9a8dd15674b047b7f5d15b3e2f27"
},
"failure_description": null
}

PATCH /v1/sources/refunds/<id>

You can update some refund fields by sending a PATCH request with a payload of any combination of the previously mentioned parameters.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/sources/refunds/2d017c99745a15ddeda9ba0e35d8e1e26d3b512a5bc5d259?merchant_id=merchantID -u accountId:APIKey -d '{
"amount": 2.0
}'