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

This is used to initialize transactions on the server-side. All properties may be specified.

bearerstring · enumOptionalPossible values:

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

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

providersstring[] | nullableOptional

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

Responses

200

Returns 200 and the transaction to retry

application/json

400

Returns 400 if the query is invalid

401

Returns 401 when authorization details is invalid

post

HTTPcURLJavaScriptPython

POST /v1/transactions/server-initialize HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1869

{
  "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

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