Transactions that have been processed outside Switch's Processing API can be imported to the platform using the External Sources service. Using External Sources you can make your transactions available in other services, such as the Transactions, Risk, Analytics, Settlements and Reporting.
External Sources must be added via API. Here you can find some examples on how to add charges, instruments, payments, and refunds using External Sources.
External sources are not forwarded to any provider.
Elements added to the platform using External Services do not follow the normal course of the other transactions. External Sources charges, instruments, payments, and refunds are made available in various services throughout the Switch Platform, but they are not forwarded to any provider.
Charges
POST /v1/sources/charges
| Method | Path | Description |
|---|---|---|
| POST | Sandbox https://merchant-api-test.switchpayments.com/v1/sources/charges Production https://merchant-api.switchpayments.com/v1/sources/charges | Add charge elements using External Sources. |
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).
operationJSON ObjectRequired
Include metadata keyword (it must be JSON object) with some external operation metadata from the provider.
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, 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: 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 designation attributed to the charge.
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 was last updated.
externalBoolean
Indicates if the charge was created as an external source.
metadataJSON Object
Provided charge metadata.
external_idsJSON Object
Provider IDs of the charge.
redirect_urlString
Redirect url defined.
instrument_paramsJSON Object
The instrument parameters used to create the charge.
request_logJSON Object
Contains information on the origin of the request: 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"}]}
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://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."]}}
Instruments
POST /v1/sources/instruments
| Method | Path | Description |
|---|---|---|
| POST | Sandbox https://merchant-api-test.switchpayments.com/v1/sources/instruments Production https://merchant-api.switchpayments.com/v1/sources/instruments | Add instrument elements using External Sources. |
Request Parameter
chargeStringRequired
The identifier of the charge that was previously created.
created_atStringRequired
The date when the charge was created (ISO 8601).
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: 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
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 was last updated.
request_logJSON Object
Contains information on the origin of the request: 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}
Payments
POST /v1/sources/payments
| Method | Path | Description |
|---|---|---|
| POST | Sandbox https://merchant-api-test.switchpayments.com/v1/sources/payments Production https://merchant-api.switchpayments.com/v1/sources/payments | Add payment elements using External Sources. |
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).
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: 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 for 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 was last updated.
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: country, ip_address, user_agent and the library_version.
paramsJSON Object
The payment parameters.
refundableBoolean
Defines whether or not the payment allows for 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}
Refunds
POST /v1/sources/refunds
| Method | Path | Description |
|---|---|---|
| POST | Sandbox https://merchant-api-test.switchpayments.com/v1/sources/refunds Production https://merchant-api.switchpayments.com/v1/sources/refunds | Add refund elements using External Sources. |
Request Parameter
paymentStringRequired
The identifier of the payment that was previously created.
amountFloatRequired
The amount to be refunded. It can be partial and it also cannot exceed the total amount of the payment.
created_atStringRequired
The date when the charge was created (ISO 8601).
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: ountry, 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. It 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: 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}