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

Authorizations

Body

application/jsontext/jsonapplication/*+json

transaction_payout_tagsobject[] | nullableoptional

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

wallet_account_tagsobject[] | nullableoptional

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

bearerstring · enumoptional

Available options:

countrystring | nullableoptional

tx_refstring | nullableoptional

Unique transaction reference.

currencystring | nullableoptional

The currency for the transaction.

amountnumber · doubleoptional

The amount of the transaction.

titlestring | nullableoptional

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

logo_urlstring | nullableoptional

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

descriptionstring | nullableoptional

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

redirect_urlstring | nullableoptional

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 | nullableread-onlyoptional

live_webhook_urlstring | nullableread-onlyoptional

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 | nullableread-onlyoptional

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

customerobjectoptional

added to allow validation of customer details

delivery_details_is_same_as_customerbooleanoptional

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

enable_instant_settlement_providers_onlybooleanoptional

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_channelsstring · enum[] | nullableoptional

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

providersstring[] | nullableoptional

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

metadataobject | nullableoptional

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 '{
    "transaction_payout_tags": [
      {
        "payout_tag": "text",
        "amount": 1,
        "description": "text",
        "metadata": {
          "ANY_ADDITIONAL_PROPERTY": {
            "options": {
              "property_name_case_insensitive": true
            },
            "parent": {
              "options": {
                "property_name_case_insensitive": true
              },
              "parent": "[Circular Reference]",
              "root": "[Circular Reference]"
            },
            "root": {
              "options": {
                "property_name_case_insensitive": true
              },
              "parent": {
                "options": {
                  "property_name_case_insensitive": true
                },
                "parent": "[Circular Reference]",
                "root": "[Circular Reference]"
              },
              "root": "[Circular Reference]"
            }
          }
        }
      }
    ],
    "wallet_account_tags": [
      {
        "account_tag": "text",
        "amount": 1,
        "description": "text",
        "metadata": {
          "ANY_ADDITIONAL_PROPERTY": {
            "options": {
              "property_name_case_insensitive": true
            },
            "parent": {
              "options": {
                "property_name_case_insensitive": true
              },
              "parent": "[Circular Reference]",
              "root": "[Circular Reference]"
            },
            "root": {
              "options": {
                "property_name_case_insensitive": true
              },
              "parent": {
                "options": {
                  "property_name_case_insensitive": true
                },
                "parent": "[Circular Reference]",
                "root": "[Circular Reference]"
              },
              "root": "[Circular Reference]"
            }
          }
        }
      }
    ],
    "bearer": "customer",
    "country": "text",
    "tx_ref": "text",
    "currency": "text",
    "amount": 1,
    "title": "text",
    "logo_url": "text",
    "description": "text",
    "redirect_url": "text",
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "full_name": "text",
      "email": "text",
      "phone_number": "text",
      "address": "text"
    },
    "delivery_details_is_same_as_customer": true,
    "enable_instant_settlement_providers_only": true,
    "payment_channels": [
      "card"
    ],
    "providers": [
      "text"
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": {
        "options": {
          "property_name_case_insensitive": true
        },
        "parent": {
          "options": {
            "property_name_case_insensitive": true
          },
          "parent": "[Circular Reference]",
          "root": "[Circular Reference]"
        },
        "root": {
          "options": {
            "property_name_case_insensitive": true
          },
          "parent": {
            "options": {
              "property_name_case_insensitive": true
            },
            "parent": "[Circular Reference]",
            "root": "[Circular Reference]"
          },
          "root": "[Circular Reference]"
        }
      }
    }
  }'

application/jsontext/jsonapplication/*+json

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