Return an Instant Payment - Lead

Return an instant payment

curl --request POST \
  --url https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "duplication",
  "additional_information": "<string>"
}
'

import requests

url = "https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return"

payload = {
    "reason": "duplication",
    "additional_information": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: 'duplication', additional_information: '<string>'})
};

fetch('https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'duplication',
    'additional_information' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return"

	payload := strings.NewReader("{\n  \"reason\": \"duplication\",\n  \"additional_information\": \"<string>\"\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))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"duplication\",\n  \"additional_information\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"duplication\",\n  \"additional_information\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "instant_payment_xyz123",
  "account_id": "account_xyz123",
  "account_number_id": "account_number_xyz123",
  "direction": "outgoing",
  "status": "posted",
  "amount": 5000,
  "currency_code": "USD",
  "debtor": {
    "name": "Alex Smith",
    "account_number": "1234567890"
  },
  "debtor_agent": {
    "routing_number": "111000111"
  },
  "creditor_agent": {
    "routing_number": "111000111"
  },
  "creditor": {
    "name": "Alex Smith",
    "account_number": "1234567890"
  },
  "payment_identifiers": {
    "end_to_end_id": "033me5upSkktRorr3J6TKZ",
    "uetr": "8dc981d2-e8c2-4a7b-8df0-0781b46328d9",
    "transaction_id": "3G0CQxK8gKLpzaaxc7A9spDiifK"
  },
  "related_objects": {
    "original_payment_id": "instant_payment_xyz123",
    "return_payment_ids": [
      "instant_payment_xyz456"
    ]
  },
  "return_requests": [
    {
      "status": "pending",
      "reason": "duplicate",
      "created_at": "2022-06-27T11:22:33Z",
      "details": "<string>",
      "deadline": "2022-07-11T23:30:00-04:00",
      "resolution": {
        "resolved_at": "2022-06-27T11:22:33Z",
        "resolved_by": "counterparty",
        "rejection_reason": "customer_no_response",
        "rejection_details": "<string>"
      }
    }
  ],
  "created_at": "2022-06-27T11:22:33Z",
  "updated_at": "2022-06-27T11:22:40Z",
  "counterparty_status": "posted",
  "description": "Payment for invoice 12345",
  "return": {
    "reason": "duplication",
    "details": "<string>"
  },
  "rejection": {
    "rejected_by": "lead",
    "reason": "non_sufficient_funds",
    "details": "<string>"
  }
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

POST

instant_payments

{instant_payment_id}

return

Return an instant payment

curl --request POST \
  --url https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "duplication",
  "additional_information": "<string>"
}
'

import requests

url = "https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return"

payload = {
    "reason": "duplication",
    "additional_information": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: 'duplication', additional_information: '<string>'})
};

fetch('https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'duplication',
    'additional_information' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return"

	payload := strings.NewReader("{\n  \"reason\": \"duplication\",\n  \"additional_information\": \"<string>\"\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))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"duplication\",\n  \"additional_information\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"duplication\",\n  \"additional_information\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "instant_payment_xyz123",
  "account_id": "account_xyz123",
  "account_number_id": "account_number_xyz123",
  "direction": "outgoing",
  "status": "posted",
  "amount": 5000,
  "currency_code": "USD",
  "debtor": {
    "name": "Alex Smith",
    "account_number": "1234567890"
  },
  "debtor_agent": {
    "routing_number": "111000111"
  },
  "creditor_agent": {
    "routing_number": "111000111"
  },
  "creditor": {
    "name": "Alex Smith",
    "account_number": "1234567890"
  },
  "payment_identifiers": {
    "end_to_end_id": "033me5upSkktRorr3J6TKZ",
    "uetr": "8dc981d2-e8c2-4a7b-8df0-0781b46328d9",
    "transaction_id": "3G0CQxK8gKLpzaaxc7A9spDiifK"
  },
  "related_objects": {
    "original_payment_id": "instant_payment_xyz123",
    "return_payment_ids": [
      "instant_payment_xyz456"
    ]
  },
  "return_requests": [
    {
      "status": "pending",
      "reason": "duplicate",
      "created_at": "2022-06-27T11:22:33Z",
      "details": "<string>",
      "deadline": "2022-07-11T23:30:00-04:00",
      "resolution": {
        "resolved_at": "2022-06-27T11:22:33Z",
        "resolved_by": "counterparty",
        "rejection_reason": "customer_no_response",
        "rejection_details": "<string>"
      }
    }
  ],
  "created_at": "2022-06-27T11:22:33Z",
  "updated_at": "2022-06-27T11:22:40Z",
  "counterparty_status": "posted",
  "description": "Payment for invoice 12345",
  "return": {
    "reason": "duplication",
    "details": "<string>"
  },
  "rejection": {
    "rejected_by": "lead",
    "reason": "non_sufficient_funds",
    "details": "<string>"
  }
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

{
  "code": "<string>",
  "title": "<string>",
  "detail": "<string>",
  "status": "<string>",
  "invalid_parameters": [
    {
      "parameter": "transaction_type",
      "reason": "<string>"
    }
  ],
  "instance": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

required

Idempotency key

Maximum string length: 255

Path Parameters

instant_payment_id

string

required

ID of the instant payment object you want to return.

Pattern: ^instant_payment_\w+$

Body

application/json

reason

enum<string>

required

The reason for the return.

Available options:

honor_return_request,

wrong_amount,

duplication,

initiating_party_unrecognized,

fraud_suspected,

undue_payment,

narrative,

customer_requested

Example:

"duplication"

additional_information

string

Accompanying free text explanation for the reason. Required if reason is "narrative" or "wrong_amount".

Maximum string length: 140

Response

The new outgoing return instant payment object.

string

required

The unique identifier of the instant payment object.

Pattern: ^instant_payment_\w+$

Example:

"instant_payment_xyz123"

account_id

string

required

The ID of the Account object.

Pattern: ^account_\w+$

Example:

"account_xyz123"

account_number_id

string

required

The ID of the Lead Bank Account Number object.

Pattern: ^account_number_\w+$

Example:

"account_number_xyz123"

direction

enum<string>

required

Who is initiating the transaction.

outgoing: You are sending a transaction to a counterparty. incoming: You are receiving a transaction from a counterparty.

Available options:

outgoing,

incoming

Example:

"outgoing"

status

enum<string>

required

The current status of the instant payment object. If outgoing: created, under_review, canceled, rejected, posted. If incoming: under_review, rejected, posted.

Available options:

created,

under_review,

canceled,

rejected,

posted

Example:

"posted"

amount

integer<int64>

required

The amount of the instant payment in cents.

Required range: x >= 0

Example:

5000

currency_code

enum<string>

required

A three-letter currency code as defined in ISO 4217.

Available options:

USD

Example:

"USD"

debtor

object

required

The details of the debtor (payer) sending the funds.

Show child attributes

debtor_agent

object

required

The details of the financial institution where the debtor (payer) holds their account.

Show child attributes

creditor_agent

object

required

The details of the financial institution where the creditor (payee) holds their account.

Show child attributes

creditor

object

required

The details of the creditor (payee) receiving the funds.

Show child attributes

payment_identifiers

object

required

The instant payment's identifiers.

Show child attributes

This instant payment's related instant payments or other objects.

Show child attributes

return_requests

object[]

required

The return requests that reference this instant payment.

Show child attributes

created_at

string<date-time>

required

The ISO 8601 format timestamp that represents when the instant payment object was created.

Example:

"2022-06-27T11:22:33Z"

updated_at

string<date-time>

required

The ISO 8601 format timestamp that represents when the instant payment object was last updated.

Example:

"2022-06-27T11:22:40Z"

counterparty_status

enum<string> | null

The current status of the instant payment from the counterparty's perspective. If outgoing: posted, under_review, or rejected. If incoming: posted or null.

Available options:

posted,

under_review,

rejected

Example:

"posted"

description

string

Free-form information on the reason for the payment.

Example:

"Payment for invoice 12345"

return

object

If this instant payment is a return, this object contains details on the return.

Show child attributes

rejection

object

If this instant payment was rejected, this object contains details on the rejection.

Show child attributes

Retrieve an Instant Payment Cancel an Instant Payment

⌘I