# 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:

```json
{
  "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.

```shell
curl --location 'https://<api-host>/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.

```json
{
    "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.

```shell
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:

```json
{
  "amount": 1000,
  "result": "Approval",
  "transaction_id": "288010185243"
}
```

You then need to inform our system of the completed refund using the following request to the `/external_refunds` endpoint.

```shell
curl --location 'https://<api-host>/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\\\"}"
    }
}'
```