Integrate custom payment gateways and methods

Swell supports numerous payment gateways, wallets, and alternative payment methods such as Stripe, Braintree, PayPal, and more. However, in certain cases you might want to integrate Swell with a payment gateway or method that is not already supported. For example, you may want to integrate Coinbase Commerce to accept cryptocurrency payments, or different payment gateways such as Adyen or Razorpay. The following guide details how to configure and manage custom payments, create payments using the Backend API, and handle refunds.

In Hosted Checkout, custom payment methods appear as payment methods during the billing stage. Customers can then select this payment method and finalize the checkout.

If you require payment info from the customer, you’ll likely want to redirect the customer to a custom page in order to capture additional billing information related to the billing method. You can do so using the Customer return link in Settings > Checkout.

If you’re building a custom checkout then you can define the exact payment flow for your custom payment method. Using the id of the payment method we created earlier, you can update a cart’s billing method using the swell.cart.update() method.

await swell.cart.update({
  billing: {
    method: 'coinbase'
  }
});

If there is any specific billing info you would want to pass along to the order, you can update the cart’s metatdata field.

await swell.cart.update({
  metadata: {
    coinbase: {
      charge_code: 'FJE4T5'
    }
  }
});

You can then submit the cart with swell.cart.submitOrder() to create an order once all other customer data is captured.

Submitting the cart with swell.cart.submitOrder() will create an order with the billing method and metadata that was included in the cart. By default, orders created with custom payment methods do not have any payments associated to them and will have an unpaid status in the Swell dashboard.

Depending on the intended payment flow, you can use a webhook firing on the order.created event, or await for the response of the submitOrder() call in order to create payments.

To create payments, you’ll have to use the Backend API by posting to the /payments endpoint. Here’s an example payload for creating a payment using swell-node with a coinbase custom payment method.

const swell = require('swell-node').init('STORE_ID', 'SECRET_KEY');

await swell.post('/payments', {
  amount: 30, //required
  method: 'coinbase', //required
  order_id: '6425a559c5aaf00012670aa9',
  account_id: '60a45168c19da965a5b399de',
  captured: true,
  authorized: true,
  charge_code: 'FJE4T5' //custom field that can be derived from order.metadata
});

Many of the fields in the snippet above are optional and are dependent on the gateway or payment method that you’re integrating. For a full list of fields and their descriptions, you can view the Payments model for more details.

In the previous example we created a payment with both authorized and captured fields set to true. If you’d like to separate these steps to create an authorization prior to capture then you can follow the following directions:

Create a payment for an authorization, making sure to set authorized: true and captured: false to ensure you’re not capturing automatically.

const swell = require('swell-node').init('STORE_ID', 'SECRET_KEY');

await swell.post('/payments', {
  amount: 30 //required
  method: 'razorpay' //required
  order_id: '6425a559c5aaf00012670aa9',
  account_id: '60a45168c19da965a5b399de',
  captured: false,
  authorized: true,
  a_custom_field: "233dsd2asdw"
});

This would create a payment that would represent an authorization. When viewing this order in the admin dashboard, you’ll notice that the payment status is “Authorized” instead of “Paid”.

You can then update the payment when the charge was captured by passing in captured: true

const swell = require('swell-node').init('STORE_ID', 'SECRET_KEY');

await swell.put('/payments/<payment_id>', {
  captured: true,
});

After this request the order will now have a paid status that reflects the captured payment.

If you want to perform refunds from the admin dashboard, you will have to configure webhooks in order to manage the communication between Swell and the custom payment method or gateway you’ve configured.

To create a webhook:

Now when you’re viewing an order with an associated payment and select refund, you’ll receive the following payload:

{
    "user_id": "6059f83ea7a1d765d211b872",
    "type": "order.refunded",
    "data": {
        "payment_id": "642c671c57df50001226dfa9",
        "payment_refund_id": "642c672603fc0c0012735871",
        "id": "6426e581239bc700125dabac"
    },
    "model": "orders",
    "date_created": "2023-04-04T18:06:31.311Z",
    "date_updated": "2023-04-04T18:06:31.413Z",
    "webhooks_pending": 2,
    "id": "642c672703fc0c0012735878"
}

Querying the /payments endpoint with the provided payment_id would allow you to retrieve all the necessary data that was passed along when the payment was created. You can then interact with the payment gateway in order to process the requested refund.