Create Payin

Create Payin

curl --request POST \
  --url https://20b9-41-90-209-232.ngrok-free.app/v1/payins \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "method": "bank_transfer",
  "target_currency": "GBP",
  "amount": 10000
}
'

const url = 'https://20b9-41-90-209-232.ngrok-free.app/v1/payins';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({method: 'bank_transfer', target_currency: 'GBP', amount: 10000})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://20b9-41-90-209-232.ngrok-free.app/v1/payins"

payload = {
    "method": "bank_transfer",
    "target_currency": "GBP",
    "amount": 10000
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://20b9-41-90-209-232.ngrok-free.app/v1/payins"

	payload := strings.NewReader("{\n  \"method\": \"bank_transfer\",\n  \"target_currency\": \"GBP\",\n  \"amount\": 10000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "object": "payin",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "stan": "<string>",
  "method": "<string>",
  "target_currency": "<string>",
  "rail_currency": "<string>",
  "amount": 123,
  "rail_amount": 123,
  "target_amount": 123,
  "scale": 123,
  "status": "<string>",
  "checkout_url": "<string>",
  "redirect_url": "<string>",
  "source_kind": "<string>",
  "collection_mode": "<string>",
  "network": "<string>",
  "instructions": {},
  "failure_reason": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "livemode": true,
  "environment": "live"
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided."
  }
}

POST

payins

Create Payin

curl --request POST \
  --url https://20b9-41-90-209-232.ngrok-free.app/v1/payins \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "method": "bank_transfer",
  "target_currency": "GBP",
  "amount": 10000
}
'

const url = 'https://20b9-41-90-209-232.ngrok-free.app/v1/payins';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({method: 'bank_transfer', target_currency: 'GBP', amount: 10000})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://20b9-41-90-209-232.ngrok-free.app/v1/payins"

payload = {
    "method": "bank_transfer",
    "target_currency": "GBP",
    "amount": 10000
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://20b9-41-90-209-232.ngrok-free.app/v1/payins"

	payload := strings.NewReader("{\n  \"method\": \"bank_transfer\",\n  \"target_currency\": \"GBP\",\n  \"amount\": 10000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "object": "payin",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "stan": "<string>",
  "method": "<string>",
  "target_currency": "<string>",
  "rail_currency": "<string>",
  "amount": 123,
  "rail_amount": 123,
  "target_amount": 123,
  "scale": 123,
  "status": "<string>",
  "checkout_url": "<string>",
  "redirect_url": "<string>",
  "source_kind": "<string>",
  "collection_mode": "<string>",
  "network": "<string>",
  "instructions": {},
  "failure_reason": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "livemode": true,
  "environment": "live"
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided."
  }
}

Authorizations

Authorization

string

header

required

Secret API key from Settings → Developers → API keys. Example: Authorization: Bearer sk_test_…

Headers

Idempotency-Key

string

required

Client-generated key so retries return the same attempt.

Required string length: 1 - 64

Body

application/json

method

string

required

Funding method (bank_transfer, momo, interac, crypto, apple_pay, …).

Example:

"bank_transfer"

target_currency

string

required

Book currency to credit.

Example:

"GBP"

amount

integer

required

Amount in Ledger minor units (target, unless rail fields set).

Example:

10000

rail_currency

string

Optional rail currency when the payer pays in a different currency.

rail_amount

integer

Amount in rail_currency minor units when set.

redirect_url

string<uri>

Return URL after hosted checkout (required for open banking / Interac / crypto checkout).

country_code

string

ISO country hint.

narration

string

Optional payment memo.

msisdn

string

Mobile number for momo.

channel

string

Momo channel id.

payer_name

string

Optional payer name.

payer_email

string<email>

Optional payer email.

Response

Funding attempt (may include checkout_url)

object

enum<string>

Object type discriminator.

Available options:

payin

string<uuid>

Payin attempt id.

stan

string

System trace / reference.

method

string

Funding method.

target_currency

string

Book currency to credit.

rail_currency

string

Currency on the payment rail when different.

amount

integer

Requested amount in target (or primary) minor units.

rail_amount

integer

Amount on the rail in rail minor units.

target_amount

integer

Expected credit to the target book in minor units.

scale

integer

Decimal places for target_currency.

status

string

Lifecycle status (pending, processing, completed, failed, …).

checkout_url

string<uri>

Hosted checkout URL when the method requires a redirect.

redirect_url

string<uri>

Return URL you supplied.

source_kind

string

Origin kind from prepare.

collection_mode

string

Prepare mode (bank_details, crypto_address, …).

network

string

Crypto network when applicable.

instructions

object

Receive instructions for the payer (account number, bank name, wallet address, etc.). Shape depends on collection_mode.

failure_reason

string

Failure message when status is failed.

created_at

string<date-time>

Creation time (UTC).

updated_at

string<date-time>

Last status change (UTC).

completed_at

string<date-time>

When the deposit completed, if successful.

livemode

boolean

true when created with a live key.

environment

enum<string>

Environment of the creating API key.

Available options:

live,

sandbox

Overview

Account

Balances

Transactions

Beneficiaries

Corridors

FX

Payouts

Swaps

Payins

Authorizations

Headers

Body

Response