Third Party Gateway Payment Flow
You can use the Third Party Gateway Payment Flow to integrate any compatible gateway with the system. After obtaining payment authorizations with the gateway, simply provide the gateway response and payment details along with any additional specifics you may need.
Below is an illustrative example of how to implement this flow.
Authorization of Payment with from a Third Party Gateway
Upon performing the authorization (with capture), the gateway will provide a response similar to the one outlined below:
{
"respstat": "A",
"token": "9601616143390000",
"retref": "984736263847",
"respcode": "00",
"resptext": "Approved",
"avsresp": "Z",
"cvvresp": "M",
"authcode": "728255",
"respproc": "FNOR",
"emv": "8A000030910A97E91E681E2734AC0012",
"binInfo": {
"country": "USA",
"product": "D",
"bin": "601101",
"cardusestring": "True credit, No PIN/Signature capability",
"gsa": false,
"corporate": false,
"fsa": false,
"subtype": "Consumer Credit - Rewards",
"purchase": false,
"prepaid": false,
"issuer": " ",
"binlo": "601100XXX",
"binhi": "601102XXX"
}
}
Create an External Payment in the Platform
The /external_payments endpoint is where you can inform us about successful payments. When making requests
to this endpoint, include the payment amount, payment method details, and the gateway response.
It's important to include a created_at timestamp in the gateway_response, which should match the
authorization time from your gateway, even if not directly provided by them. This timestamp is crucial
for matching settlement records to payments during the settlement process. Additionally, make sure
to map authcode to auth_code and retref to retrieval_reference within the gateway_response object.
Below is a cURL example for recording an external authorization in our system, using the example
authorization response mentioned. Take note of how the authcode (728255) and retref (984736263847)
values are mapped in the external payments request body.
curl --location 'https://api.getfwd.com/external_payments' \
--header 'x-account-id: acct_2TXMC34dvHW8LkSN87DN4oiO69l' \
--header 'x-api-key: key_123456789' \
--header 'Content-Type: application/json' \
--data '{
"payment_intent": {
"amount": 4999
},
"payment_method": {
"payment_method_type": "card",
"source_type": "external",
"card": {
"token": "external",
"last_four_digits": "2311",
"first_six_digits": "424223",
"brand": "visa",
"exp_month": "1",
"exp_year": "2024"
}
},
"gateway_response": {
"auth_code" : "728255",
"retrieval_reference": "984736263847",
"created_at": "2023-08-25T19:34:51.815Z",
"raw_response":"{\\"respstat\\":\\"A\\",\\"token\\":\\"9601616143390000\\",\\"retref\\":\\"984736263847\\",\\"respcode\\":\\"00\\",\\"resptext\\":\\"Approved\\",\\"avsresp\\":\\"Z\\",\\"cvvresp\\":\\"M\\",\\"authcode\\":\\"728255\\",\\"respproc\\":\\"FNOR\\"}"
}
}'
Making this call will create a payment intent, and it's crucial to retain the id of this payment intent within your database. This id will serve as a reference for executing future actions, like initiating a refund (as outlined below).
{
"id": "pi_2UURIXJ5jxdHJ6ksdM07thFcFvp",
"entity": "payment_intent",
"status": "captured",
"amount": 4999,
"amount_authorized": 169,
"amount_captured": 169,
"amount_refunded": 0,
"amount_voided": 0,
"amount_disputed": 0,
"tax_amount": 0,
"tip_amount": 0,
"surcharge_amount": 0,
"payment_splits": [],
"capture": true,
"currency": "USD",
"latest_payment": {
"id": "pmt_2UURIXTthG1QOyPwrvEs3Nd9QQl",
"entity": "payment",
"status": "captured",
"amount": 4999,
"amount_authorized": 4999,
"amount_captured": 4999,
"amount_refunded": 0,
"amount_voided": 0,
"amount_disputed": 0,
"payment_intent_id": "pi_2UURIXJ5jxdHJ6ksdM07thFcFvp",
"payment_method_id": "pm_2UUNSAZqtzNQP05w7jZyGMrN6oP",
"payment_method": {
"id": "pm_2UUNSAZqtzNQP05w7jZyGMrN6oP",
"entity": "payment_method",
"created_at": "2023-08-25T19:03:16.855Z",
"updated_at": "2023-08-25T19:03:16.855Z",
"payment_method_type": "card",
"source_type": "card_pointe",
"card": {
"last_four_digits": "2311",
"first_six_digits": "424223",
"brand": "visa",
"exp_month": "01",
"exp_year": "2024"
}
},
"auth_code": "728255",
"external": true,
"created_at": "2023-08-25T19:34:52.342Z",
"updated_at": "2023-08-25T19:34:52.342Z",
"account_id": "acct_2TXMC34dvHW8LkSN87DN4oiO69l",
"settlement_status": "unsettled"
},
"external": true,
"partner_id": "part_1234",
"business_id": "bus_2OafJPlpPB5WZdp9GYaoeR9pCmC",
"account_id": "acct_2TXMC34dvHW8LkSN87DN4oiO69l",
"created_at": "2023-08-25T19:34:52.231Z",
"updated_at": "2023-08-25T19:34:52.344Z",
"captured_at": "2023-08-25T19:34:52.343Z",
"settlement_status": "unsettled"
}
Refund an external payment
Similarly, as with the third party gateway capture process detailed earlier, we offer the /external_refunds
endpoint that enables developers to inform our system about refunds conducted for payments authorized externally.
To initiate this, you should first call your gateway API and generate a refund. See the following cURL command for an example of how this might be done.
curl --location 'https://my-gateway.com/refund' \
--header 'Content-Type: application/json' \
--data '{
"original_transaction_id": "984736263847",
"amount": 1000
}'
Making this call will produce a response similar to the following:
{
"amount": 1000,
"result": "Approval",
"transaction_id": "288010185243"
}
You then needt to inform our system of the completed refund using the
following request to the /external_refunds endpoint.
curl --location 'https://api.getfwd.com/external_refunds' \
--header 'x-account-id: acct_2TXMC34dvHW8LkSN87DN4oiO69l' \
--header 'x-api-key: key_123456789' \
--header 'Content-Type: application/json' \
--data '{
"payment_intent_id": "pi_2UURIXJ5jxdHJ6ksdM07thFcFvp",
"gateway_response": {
"created_at": "2023-08-25T19:41:23.403Z",
"raw_response":"{\\"amount\\":1000,\\"result\\":\\"Approval\\",\\"transaction_id\\":\\"288010185243\\"}"
}
}'