Initialize a transaction

Initiate a payment request to accept payment

NOTE: This section describes how to initialize a transaction on the server-side ie within your own application server using secret keys. To initialize a transaction on the client side (ie using public API keys), check out the quickstart section.

This API endpoint initializes a new payment from your backend/server.

A currency, amount, and customer object (with at least the customer's email) must be supplied. The customer is added to your list of customers if they do not already exist.

You may also provide a tx_ref (transaction reference) for the payment transaction. This must be a unique alpha-numeric string that cannot be repeated again in your transaction list (for at least 2 years). If you do not know how to generate this, we've got you. Leave it blank and we will fill it in.

NOTE: Initializing a transaction only indicates you want a customer to make a payment. However, the customer may cancel without completing the payment or payment may simply fail. So always make sure you verify the transaction status before giving value.

Initializes a new transaction from the merchant's server on the merchant's profile.

POST/v1/transactions/server-initialize

Body

application/jsontext/jsonapplication/*+json

An object containing the details of transaction to initialize

transaction_payout_tagsnullable array of CreateTransactionPayoutTagDto (object)

Collection of tags indicating bank accounts to settle the transaction payout.

wallet_account_tagsnullable array of CreateWalletAccountTagDto (object)

Collection of tags indicating wallet accounts to settle a top-up.

bearerChargeBearer (enum)

customermerchant

countrynullable string

tx_refnullable string

Unique transaction reference.

currencynullable string

The currency for the transaction.

amountnumber (double)

The amount of the transaction.

titlenullable string

The title of the transaction at checkout (if provided).

logo_urlnullable string

The link to the logo displayed during checkout (if provided).

descriptionnullable string

A description for the payment displayed during checkout (if provided).

redirect_urlnullable string

The dynamic redirect URL for the transaction. Used if the desired redirect url is different from the static redirect url set on the dashboard

sw_app_redirect_urlnullable string

live_webhook_urlnullable string

The dynamic live webhook URL for the transaction. Used if the desired webhook url is different from the static live webhook url set on the dashboard

test_webhook_urlnullable string

The dynamic test webhook URL for the transaction. Used if the desired webhook url is different from the static test webhook url set on the dashboard

customerPaymentCustomerDto (object)

added to allow validation of customer details

delivery_details_is_same_as_customerboolean

Indicates that a sale is to be delivered to the customer not a different person.

enable_instant_settlement_providers_onlyboolean

setting this flag will disable gateways that settle T+1 ie only instant settlement providers will be enabled. This flag enforces instant settlement on the corresponding on the payment link created

payment_channelsnullable array of PaymentMethods (enum)

(Optional) Payment channels you want to enable at checkout for your customers eg card, qrCode, etc

providersnullable array of string

(Optional) Payment providers you want to enable at checkout for your customers eg flutterwave, paystack, etc

metadatanullable object

Metadata to attach to the transaction

Response

200400401

Returns 200 and the transaction to retry

Body

application/json

hosted_pagenullable string

tx_refnullable string

Request

JavaScriptCurlPython

const response = await fetch('/v1/transactions/server-initialize', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "hosted_page": "text",
  "tx_ref": "text"
}

curl

curl https://api.switchappgo.com/v1/transactions/server-initialize \
    -H "authorization: 'bearer sk_test_nTgS42KNdKr6Ts798DT'" \
    -d amount='3000' \
    -d currency='USD' \
    -d customer='{"email":"[e-mail]"}'

node

const switchapp = require('switchapp')('sk_test_nTgS42KNdKr6Ts798DT');

const newTx = await switchapp.transactions.serverInitialize({
    amount: 3000,
    currency: 'USD',
    customer: { email:'[e-mail]' },
})