Third Party Gateway Payment Flow

You can use the Third Party Gateway Payment Flow to integrate CardPointe direct payments with the system. After obtaining payment authorizations, simply provide the gateway response and essential payment details along with any payment split instructions.

Below is an illustrative example of how to implement this flow.

Authorization of Payment with CardPointe

Upon performing the authorization (with capture), CardPointe 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 Forward

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 CardPointe, 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 CardPointe 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": "cardpointe",
        "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 the CardPointe API and generate a refund. See the following cURL command for an example of how to do this. Remember, you'll need the retref value from the previous payment and the merchant's id to complete the refund.

curl --location 'https://cardconnect.com/cardconnect/rest/refund' \
--header 'Content-Type: application/json' \
--data '{
    "retref": "984736263847",
    "merchid": "123456789012"
}'

Making this call will produce a response similar to the following:

{
  "respproc": "PPS",
  "amount": "59.60",
  "resptext": "Approval",
  "retref": "288010185243",
  "respstat": "A",
  "respcode": "00",
  "merchid": "123456789012"
}

You can use the retref value from this refund 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",
        "retrieval_reference": "71854700",
        "raw_response":"{\\"respproc\\":\\"PPS\\",\\"amount\\":\\"59.60\\",\\"resptext\\":\\"Approval\\",\\"retref\\":\\"288010185243\\",\\"respstat\\":\\"A\\",\\"respcode\\":\\"00\\",\\"merchid\\":\\"123456789012\\"}"
    }
}'

Third Party Gateway Payment Flow

Authorization of Payment with CardPointe​

Create an External Payment in Forward​

Refund an external payment​

Authorization of Payment with CardPointe

Create an External Payment in Forward

Refund an external payment