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

Authorizations

Body

application/jsontext/jsonapplication/*+json

bearerstring · enum

Options: customer, merchant

countrystring | nullable

tx_refstring | nullable

Unique transaction reference.

currencystring | nullable

The currency for the transaction.

amountnumber · double

The amount of the transaction.

titlestring | nullable

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

logo_urlstring | nullable

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

descriptionstring | nullable

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

redirect_urlstring | nullable

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_urlstring | nullable

live_webhook_urlstring | nullable

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_urlstring | nullable

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

customerobject

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

transaction_payout_tagsobject[] | nullable

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

wallet_account_tagsobject[] | nullable

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

payment_channelsstring · enum[] | nullable

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

providersstring[] | nullable

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

metadataobject | nullable

Metadata to attach to the transaction

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/transactions/server-initialize' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"bearer":"customer","customer":{},"transaction_payout_tags":[{"metadata":{"ANY_ADDITIONAL_PROPERTY":{"options":{},"parent":{"options":{},"parent":"[Circular Reference]","root":"[Circular Reference]"},"root":{"options":{},"parent":{"options":{},"parent":"[Circular Reference]","root":"[Circular Reference]"},"root":"[Circular Reference]"}}}}],"wallet_account_tags":[{"metadata":{"ANY_ADDITIONAL_PROPERTY":{"options":{},"parent":{"options":{},"parent":"[Circular Reference]","root":"[Circular Reference]"},"root":{"options":{},"parent":{"options":{},"parent":"[Circular Reference]","root":"[Circular Reference]"},"root":"[Circular Reference]"}}}}],"payment_channels":["card"],"providers":[null],"metadata":{"ANY_ADDITIONAL_PROPERTY":{"options":{},"parent":{"options":{},"parent":"[Circular Reference]","root":"[Circular Reference]"},"root":{"options":{},"parent":{"options":{},"parent":"[Circular Reference]","root":"[Circular Reference]"},"root":"[Circular Reference]"}}}}'

200

400

401

200

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

Returns 200 and the transaction to retry

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]' },
})