Simulating a Payout Returned Status

Use this method in the sandbox to simulate the action of a third party that is required for returning the payout.

Relevant when the status of the payout is Completed.

Prerequisites:

This method triggers the Payout Returned Webhook. This webhook contains the same information as the response.

Parameters

Request Path Parameters

- payout
- ID of the payout. String starting with payout_.

Request Header Parameters

Response Parameters

- amount
- Amount of the payout, in units defined by payout_currency. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Same as payout_amount.
- batch_file
- Batch file ID. Relevant to batch payouts that were created via the Client Portal.
- beneficiary
- Object describing the beneficiary.
- beneficiary_country
- Beneficiary bank country. The country to which funds are sent. Two-letter ISO 3166-1 ALPHA-2 code.
- bin_details
- Bank identification details. Relevant to cards.
  bin_number
  Bank identification number of the issuing bank.
  brand
  The brand of the card.
  country
  The country where the card was issued.
  issuer
  Name of the bank that issued the card.
  level
  The level of the card.
  type
  The type of card.
- created_at
- Time of creation of the payout object, in Unix time.
- error
- Indicates the error code of the last unsuccessful operation on the payout object.
- estimated_time_of_arrival
- The estimated time period in which the beneficiary will receive the funds.
  Note
  Rapyd will try to complete the payout within the estimated time. However, completion of a payout can be delayed for legal or other reasons.
- ewallets
- An array of one object, which contains the following fields:
  ewallet_id
  The ID of the wallet that the money is transferred from, a string starting with ewallet_.
  amount
  Amount of the transaction in currency units defined in currency.
  percent
  A decimal number representing a percentage of the total payout.
- expiration
- Determines the day the payout expires, in Unix time. The payout must be completed before the start of this day.
  Relevant to cash payout methods where the is_expirable field is true in the response to List Payout Method Types.
- fx_rate
- Currency conversion rate for the payout. Decimal.
- gc_error_code
- Reserved.
- id
- ID of the payout. String starting with payout_.
- identifier_type
- Reserved.
- identifier_value
- Reserved.
- instructions
- Describes how the customer collects the payout. Contains the following fields:
  name
  Description of the payment method.
  steps
  An array containing a list of steps for the customer to take. Each step is named stepN, where N is an integer.
- merchant_reference_id
- Identifier defined by the client for reference purposes. Limit: 45 characters.
- metadata
- A JSON object defined by the client. See Metadata.
- paid_amount
- Cumulative amount received by the beneficiary, in units defined by payout_currency.
- paid_at
- Time of the payout, in Unix time.
- payout_currency
- Currency received by the beneficiary. Three-letter ISO 4217 code.
- payout_fees
- Object that defines transaction fees and foreign exchange fees that the client can define for payout transactions.
  transaction_fee
  Describes the fee for processing the transaction.
  calc_type
  Specifies how the fee is calculated. One of the following:
  net - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet.
  gross - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00.
  fee_type
  One of the following:
  percentage - A percentage of the transaction amount. For example, 5 percent is represented by value=5.
  absolute - A fixed amount.
  value
  The amount of the fee.
  fx_fee
  Describes the fees for processing the currency exchange. Relevant to payments with FX.
  calc_type
  Specifies how the fee is calculated. One of the following:
  net - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet.
  gross - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00.
  value
  The amount of the fee. Percentage.
  gross_fees
  The total gross fees for the transaction, in units defined by currency_code.
  net_fees
  The total net fees for the transaction, in units defined by merchant_requested_currency.
  total_merchant_fees
  The amount of the fee.
- payout_method_type
- The type of payout method. The two-letter prefix must match the country code of the beneficiary.
- payout_type
- The type of the payout method. One of the following values:
  - bank - Payout to bank account.
  - card - Payout to card.
  - cash - Payout to cash.
  - ewallet - Payout to local eWallet.
- sender
- Object describing the sender.
  company_name
  Name of the sender company. Relevant when entity_type is company.
  country
  Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code.
  currency
  Currency that the sender is paying with. Three-letter ISO 4217 code.
  entity_type
  Type of entity. One of the following values:
  company
  individual
  first_name
  First name of the sender. Relevant when entity_type is individual.
  identification_type
  Type of identification document for the sender. When entity_type is company, this field must be company_registered_number. When entity_type is individual, one of the following values:
  drivers_license
  identification_id
  international_passport
  residence_permit
  social_security
  work_permit
  identification_value
  Identification number on the document mentioned in identification_type.
  last_name
  Last name of the sender. Relevant when entity_type is individual.
- sender_amount
- Amount that the sender is paying in units of the currency defined in sender_currency. This amount remains the same regardless of FX fees. Decimal.
- sender_country
- Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code.
- sender_currency
- Currency that the sender is paying with. Three-letter ISO 4217 code.
- statement_descriptor
- A statement that includes the reason for the payout. Limited to 35 characters.
- status
- Indicates the status of the payout. One of the following:
  - Canceled - The payout was canceled.
  - Completed - The beneficiary received some or all payout funds.
  - Confirmation - The payout is waiting for the beneficiary to confirm the FX rate.
  - Created - The payout was created successfully.
  - Declined - The payout failed to pass inspection.
  - Error - The payout was not created or failed after creation.
  - Expired - The payout has expired.
  - Hold - A bank payout is being reviewed manually by Rapyd Protect. A Quarantine Under Review Webhook is also triggered.
  - Pending - The payout is waiting for the beneficiary to confirm acceptance of the funds.
  - Returned - Funds were returned to after the payout was completed.

.NET

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var payout = "payout_cd35fbe8dc6fd7c2e67d44ad53a4367d";               

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/payouts/return/{payout}", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

JavaScript

const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {};
    const result = await makeRequest(
      'POST',
      '/v1/payouts/return/payout_cd35fbe8dc6fd7c2e67d44ad53a4367d/',
      body
    );

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

PHP

<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('post', '/v1/payouts/return/payout_cd35fbe8dc6fd7c2e67d44ad53a4367d');
    var_dump($object);
} catch(Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

payout = 'payout_cd35fbe8dc6fd7c2e67d44ad53a4367d'  
results = make_request(method='post',
                       path=f'/v1/payouts/return/{payout}')
pprint(results)

/v1/payouts/return/:payout/

Return Payout

curl -X post
https://sandboxapi.rapyd.net/v1/payouts/return/payout_f85eca81e10e2a0bd6bf0ac5ed35a926/
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'idempotency: your-idempotency-parameter-here'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "465b4fc9-7845-44ba-a0ec-7204a0ab88c8"
    },
    "data": {
        "id": "payout_a5dfe5d57303d7bafb4644a43ba7493d",
        "payout_type": "bank",
        "payout_method_type": "gp_sepa_bank",
        "amount": 61,
        "payout_currency": "EUR",
        "sender_amount": 53.06,
        "sender_currency": "GBP",
        "status": "Returned",
        "sender_country": "US",
        "sender": {
            "id": "sender_bd2668b021895154506e4b581c0c2a0e",
            "country": "US",
            "entity_type": "company",
            "address": "1 St Katharines Way St Katharines Wapping London E1W 1UN",
            "name": "Cashdash UK Ltd",
            "date_of_incorporation": "08/10/1990",
            "postcode": "934539",
            "city": "AE Limbd",
            "phone_number": "447470554081",
            "company_name": "Cashdash UK Ltd",
            "currency": "GBP",
            "identification_type": "company_registered_number",
            "identification_value": "10207686",
            "beneficiary_relationship": "customer",
            "source_of_income": "business_income"
        },
        "beneficiary_country": "GP",
        "beneficiary": {
            "id": "beneficiary_de1f84ad75f48315e7fc7627779a96d2",
            "last_name": "Meme",
            "first_name": "Mehmet",
            "country": "GP",
            "entity_type": "individual",
            "address": "a2123",
            "name": "Mehmet Meme",
            "date_of_birth": "13/10/1990",
            "postcode": "12333",
            "city": "test",
            "phone_number": "12303839",
            "currency": "EUR",
            "identification_type": "identification_id",
            "identification_value": "***********",
            "bank_name": "CREDIT AGRICOLE S A",
            "bic_swift": "AGRIFRPPXXX",
            "iban": "FR7630006000011234567890189",
            "default_payout_method_type": "gp_sepa_bank"
        },
        "fx_rate": 1.1496977598,
        "instructions": [
            {
                "name": "instructions",
                "steps": [
                    {
                        "step1": "The funds will be transferred to the provided account details of the beneficiary"
                    }
                ]
            }
        ],
        "instructions_value": {},
        "ewallets": [
            {
                "ewallet_id": "ewallet_f69bdf976830363ec0146418f31ea4c1",
                "amount": 53.06,
                "percent": 100
            }
        ],
        "metadata": {},
        "description": "mydecsr",
        "created_at": 1728474259,
        "payout_fees": null,
        "expiration": null,
        "merchant_reference_id": null,
        "paid_at": null,
        "identifier_type": null,
        "identifier_value": null,
        "error": null,
        "paid_amount": 0,
        "statement_descriptor": null,
        "gc_error_code": null,
        "batch_file": null
    }
}

In this section:

Documentation

Simulating a Payout Returned Status

Parameters

Request Path Parameters

Request Header Parameters

Response Parameters

Note

Search results