Skip to main content

Accept Payments

Introduction​

There are 3 technical steps to accept payment transactions.

  1. Creating a Payment Intent Using the API
  2. Use Payment Elements (SDK) to Collect the Card Data Securely
  3. Send the Tokenized Data to the API for Processing

Forward takes over from there, presenting your payment to the networks, applying the appropriate fees, and working with the banking system to get those funds in your customer’s hands as soon as possible.

Environments​

1. Creating a Payment Intent Using the API​

Context​

A Payment Intent is a record that represents a payment transaction. The Payment Intent contains details about the transaction, such as the amount, currency, and account.

Create the Payment Intent​

From your backend, make a call to the /payment_intents endpoint. Include the amount (cents) to be collected in the request body.

curl -X POST "https://api.getfwd.com/payment_intents" \
    -H  "x-account-id: acct_12345678" \
    -H  "x-api-key: key_123456789" \
    -d '{
          "amount": 1000
        }'

This will create a Payment Intent record similar to the following:

{
  "id": "pi_2SG6ibTHTo4N6Sdx6Oh66IGg3o3",
  "entity": "payment_intent",
  "status": "created",
  "client_secret": "pi_2SG6ibTHTo4N6Sdx6Oh66IGg3o3_secret_12345678",
  "amount": 1000,
  "amount_authorized": 0,
  "amount_captured": 0,
  "amount_refunded": 0,
  "amount_voided": 0,
  "amount_disputed": 0,
  "tax_amount": 0,
  "tip_amount": 0,
  "surcharge_amount": 0,
  "payment_splits": [],
  "capture": true,
  "currency": "USD",
  "partner_id": "par_12345678",
  "business_id": "bus_12345678",
  "account_id": "acct_12345678",
  "reference_id": "some-ref-id",
  "created_at": "2023-07-14T17:16:34.651Z",
  "updated_at": "2023-07-14T17:16:34.651Z"
}

2. Launch Payment Elements (SDK) to collect the card data securely​

Context​

In your software application, where your customer would naturally collect payment from their customer, you need to provide a means to collect the credit card data. This data is protected and regulated to avoid hackers from compromising accounts. We built a powerful browser-side JavaScript library that integrates a secure credit card payment form into your application. Refer to the Payment Elements SDK section for more details.

Example of adding Payment Element to a site​

<div id="payment-form"></div>

<script>
  const paymentForm = await Forward.createPaymentElement({
    apiKey: 'pk_123948342832',
    clientSecret: 'pi_123948342832_secret_123948342832',
  });
  paymentForm.mount('#payment-form', {
    onReady: (tokenize) => {
      tokenize();
    },
    onSuccess: async ({ token }) => {
      console.log('paymentMethodId', token);
    }
  });
</script>

The onSuccess callback is passed a token representing a PaymentMethod id for creating a payment.

3. Send the Transaction to the API for Processing​

Context​

At this point, your customer has an approved merchant account, you have securely collected the credit card information from their customer, and you are ready to send the payment to Forward for processing. You are milliseconds away from telling your customer whether the payment was accepted.

Create a payment​

To initiate the payment, make a request to the /payment_intents/:id/payments endpoint. Include id's for the Payment Intent and Payment Method in the url and request body, respectively.

curl --location 'https://api.getfwd.com/payment_intents/pi_2SG6ibTHTo4N6Sdx6Oh66IGg3o3/payments' \
--header 'x-account-id: acct_2PbifDOE5oaNLyy0oKzXMmHzCeK' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--data '{
    "payment_method_id": "pm_2SXKvZzhPgZJ4nbcVq8UB9eT1B7"
}'

A successfully processed payment will result in a response similar to the following:

{
  "id": "pi_2SG6ibTHTo4N6Sdx6Oh66IGg3o3",
  "entity": "payment_intent",
  "status": "captured",
  "amount": 1000,
  "amount_authorized": 0,
  "amount_captured": 1000,
  "amount_refunded": 0,
  "amount_voided": 0,
  "amount_disputed": 0,
  "tax_amount": 0,
  "tip_amount": 0,
  "surcharge_amount": 0,
  "payment_splits": [],
  "order_details": {},
  "capture": false,
  "currency": "USD",
  "latest_payment": {
    "id": "pmt_2SZXERaQpYmJyZVssb2lqAOF7H0",
    "entity": "payment",
    "status": "captured",
    "amount": 1000,
    "amount_authorized": 0,
    "amount_captured": 1000,
    "amount_refunded": 0,
    "amount_voided": 0,
    "amount_disputed": 0,
    "payment_intent_id": "pi_2SG6ibTHTo4N6Sdx6Oh66IGg3o3",
    "payment_method_id": "pm_2SXKvZzhPgZJ4nbcVq8UB9eT1B7",
    "payment_method": {
      "id": "pm_2SXKvZzhPgZJ4nbcVq8UB9eT1B7",
      "entity": "payment_method",
      "created_at": "2023-07-13T22:35:16.921Z",
      "updated_at": "2023-07-13T22:35:16.921Z",
      "payment_method_type": "card",
      "card": {
        "last_four_digits": "2384",
        "first_six_digits": "424242",
        "brand": "visa",
        "exp_month": "01",
        "exp_year": "25"
      }
    },
    "created_at": "2023-07-14T17:16:04.667Z",
    "updated_at": "2023-07-14T17:16:04.667Z",
    "account_id": "account_78746",
    "reference_id": "some-ref-id",
    "settlement_id": "se_2SZXGV1LC3v4INx2nTPk1xnBkcH",
    "settlement_status": "unsettled"
  },
  "account_id": "acct_12345678",
  "reference_id": "some-ref-id",
  "created_at": "2023-07-14T17:14:58.603Z",
  "updated_at": "2023-07-14T17:16:20.751Z",
  "captured_at": "2023-07-14T17:16:20.750Z",
  "settlement_id": "se_2SZXGV1LC3v4INx2nTPk1xnBkcH",
  "settlement_status": "unsettled"
}

For more information about the API, refer to the Payments API Reference.