Administrar el depósito en garantía

Retenga cualquier método de pago en depósito en garantía para su posterior liberación.

Retener un pago en depósito en garantía

Un depósito en garantía es un acuerdo para retener fondos en una transacción entre dos o más partes. Los depósitos en garantía ayudan a liquidar un intercambio entre un comprador y un vendedor en función de los requisitos acordados. Cuando un comprador realiza una compra de alto valor y los fondos se mantienen en depósito en garantía, los fondos se retienen para uno o varios vendedores y se pueden liberar de las siguientes maneras

Liberación total o parcial bajo demanda.
Liberación automáticamente después de un número específico de días.
Las liberaciones parciales se pueden liberar por cantidad o porcentaje y de forma proporcional o no proporcional.

El depósito en garantía es una función de Rapyd Collect que funciona con el back-end de su sitio web y retiene los fondos en un Rapyd Wallet. Cuando se realiza la compra, el back-end de su sitio web solicita a Rapyd que procese el pago; a continuación, los fondos se retienen en la billetera. Posteriormente, los fondos se liberan al vendedor del artículo de acuerdo con el acuerdo predeterminado con el vendedor o a solicitud. Cuando se libere el dinero, Rapyd le notifica a través de un webhook que la transferencia se completó correctamente.

Flujo de trabajo de varias liberaciones para un vendedor

Un cliente compra un artículo por 250 USD (dólares estadounidenses) a un vendedor en su plataforma. Retiene los fondos que pagó el cliente en depósito en garantía. Libera automáticamente un monto parcial de los fondos transcurridos 5 días y libera el resto de los fondos al vendedor a solicitud, de acuerdo con sus políticas empresariales.

Certificación PCI

Solo clientes con certificación PCI-DSS pueden gestionar la información de identificación personal de las tarjetas. Este servicio está disponible para los comercios que hayan firmado un acuerdo especial con Rapyd

Paso 1: Procesar el pago en depósito en garantía

Puede encontrar los métodos de pago específicos que aceptará y los campos obligatorios correspondientes que los clientes deben llenar en la sección Cómo funciona.

Un cliente de su plataforma compra un producto a un vendedor.
El back-end del sitio web le pide a Rapyd que procese la transacción y mantenga los fondos en depósito en garantía durante cinco días.
Rapyd procesa los pagos y mantiene los fondos en depósito en garantía.

Paso 2: Liberar los fondos en depósito en garantía

El back-end del sitio web le pide a Rapyd que libere parte de los fondos para el vendedor.
Rapyd libera automáticamente parte de los fondos para el vendedor y continúa manteniendo los fondos restantes en depósito en garantía.
Rapyd libera manualmente los fondos en depósito en garantía restantes al vendedor en función de la entrega del artículo de alto valor.

Estados de depósito en garantía

El siguiente diagrama de estados finitos resume los estados de los pagos en depósito en garantía.

Descripción de los estados

Estado	Descripción
pending	Se crearon el pago y el depósito en garantía, pero el pago no se ha completado y los fondos no están en depósito en garantía.
on_hold	El pago se ha completado y los fondos están en depósito en garantía.
released	La totalidad o parte de los fondos se han entregado a las billeteras.
canceled	Se cancela el depósito en garantía.

Cómo funciona la administración del depósito en garantía

Prerrequisitos

Para ejecutar los ejemplos de este caso de uso, debe crear los siguientes ID en su propio sandbox:

ewallet_ - Ejecute Crear una billetera para el Rapyd Wallet del vendedor del teléfono. Use la «ID» que obtiene en la respuesta. Para obtener más información, ver Creación de una billetera Rapyd. Repita para la billetera del vendedor del altavoz.

Buscar métodos de pago disponibles

En tu página de pago, permite que el cliente seleccione un método de pago. En primer lugar, debe decidir qué métodos de pago aceptará. En este ejemplo, comprobará si hay métodos de pago en USD (dólares estadounidenses) en los Estados Unidos.

Para eso, utilizará Listar los métodos de pago por país con los siguientes parámetros.

Descripción de los parámetros de consulta

Parámetro de consulta	Descripción
país	Introduzca US como el código del país para los Estados Unidos.
currency	Introduzca USD como el código de la moneda para los dólares estadounidenses.

Solicitud de lista de métodos de pago por país

Solicita la lista de todos los métodos de pago estadounidenses disponibles en USD.

Solicitud

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

// Message body absent

.NET Core

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string country = "US";
                string currency = "USD";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/country?country={country}&currency={currency}");

                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 result = await makeRequest('GET', '/v1/payment_methods/country?country=US&currency=USD');

    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('get', '/v1/payment_methods/country?country=US&currency=USD');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

results = make_request(method='get',
                       path=f'/v1/payment_methods/country?country=US&currency=USD')
pprint(results)

Respuesta de la lista de métodos de pago por país

Veamos la respuesta.

Respuesta

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "2ef3f76f-6a57-4d1f-bf60-162313d304bc"
    },
    "data": [
        {
            "type": "us_debit_visa_card",
            "name": "Visa",
            "category": "card",
            "image": "https://iconslib.rapyd.net/checkout/us_visa_card.png",
            "country": "US",
            "payment_flow_type": "card",
            "currencies": [
                "USD"
            ],
            "status": 1,
            "is_cancelable": false,
            "payment_options": [],
            "is_expirable": false,
            "is_online": false,
            "minimum_expiration_seconds": null,
            "maximum_expiration_seconds": null
        }
    ]
}

La sección data de esta respuesta muestra que us_debit_visa_card es un método de pago aceptable.

Nota: Una respuesta real suele incluir muchos métodos de pago.

Encontrar los campos obligatorios para el método de pago

Debe averiguar qué campos el cliente necesita llenar para el método de pago.

Para eso, utilizará Obtener campos obligatorios del método de pago con el siguiente parámetro:

Descripción de los parámetros de ruta

Parámetro de ruta	Descripción
type	Introduzca us_debit_visa_card como el tipo de método de pago.

Solicitud de obtener campos obligatorios del método de pago

Solicita el conjunto de campos obligatorios para un pago us_debit_visa_card.

Solicitud

/ Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/us_debit_visa_card/required_fields

// Message body absent

.NET Core

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string type = "us_visa_card";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/{type}/required_fields");

                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 result = await makeRequest('GET', '/v1/payment_methods/us_visa_card/required_fields');

    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('get', '/v1/payment_methods/us_visa_card/required_fields');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

payment_method = 'us_visa_card'
results = make_request(method='get',
                       path=f'/v1/payment_methods/{payment_method}/required_fields')
pprint(results)

Respuesta de obtener campos obligatorios del método de pago

Veamos la respuesta.

Respuesta

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "0cd7be44-fd91-4b27-941f-158f5e47fb7c"
    },
    "data": {
        "type": "us_debit_visa_card",
        "fields": [
            {
                "name": "number",
                "type": "string",
                "regex": "",
                "is_required": true,
                "instructions": "card number"
            },
            {
                "name": "expiration_month",
                "type": "string",
                "regex": "",
                "is_required": true,
                "instructions": "expiration month as string, 01-12"
            },
            {
                "name": "expiration_year",
                "type": "string",
                "regex": "",
                "is_required": true,
                "instructions": "expiration year in to digits as string, 18-99"
            },
            {
                "name": "cvv",
                "type": "string",
                "regex": "",
                "is_required": true,
                "instructions": "card cvv"
            },
            {
                "name": "name",
                "type": "string",
                "regex": "",
                "is_required": false,
                "instructions": "card holder name"
            },
            {
                "name": "address",
                "type": "Address",
                "regex": "",
                "is_required": false,
                "instructions": "card billing address. see Address object for more details"
            }
        ],
        "payment_method_options": [
            {
                "name": "3d_required",
                "type": "string",
                "regex": "",
                "description": "",
                "is_required": false,
                "is_updatable": false
            }
        ],
        "payment_options": [],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null
    }
}

La sección data de esta respuesta muestra que se requieren cinco campos para un pago us_debit_visa_card. Estos campos son number, expiration_month, expiration_year, cvv, y name.

Crear el pago y el depósito en garantía

John Doe realiza las siguientes compras en el sitio web de su plataforma:

Un altavoz de un vendedor por USD 50,00 (dólares estadounidenses).
Un teléfono de otro vendedor por 200 USD (dólares estadounidenses).

Solicita a Rapyd que procese el pago e incluya un depósito en garantía para retener los fondos durante cinco días.

Para eso, utilizará Crear pago con los siguientes parámetros:

Descripción de los parámetros del cuerpo

Parámetro del cuerpo	Descripción
amount	Introduzca 250 como el monto total del pago.
currency	Introduzca USD como el código para dólares estadounidenses.
payment_method	Introduzca un objeto 'payment_method' que tenga los siguientes campos: `type` - Introduzca us_debit_visa_card como el tipo de tarjeta de crédito. Introduzca un objeto «fields» que tenga los siguientes campos: `number` - Introduzca 4111111111111111 . `expiration_month` - Introduzca 10. `expiration_year` - Introduzca 22. `cvv` - Introduzca 123. `name` - Introduzca John Doe.
ewallets	Introduzca una matriz de «ewallets» que tenga dos objetos con los siguientes campos: Primer objeto: `ewallet` - Introduzca el «ID» de Rapyd Wallet que recibió cuando creó la billeterea del vendedor de altavoces en su sandbox. Para los fines de esta lección de caso de uso, estamos usando ewallet_090e1ef18c3aa754fd43cce9ee454858, que es el ID de la billetera que hemos creado en nuestro sandbox. `amount` - Introduzca 50 como monto a pagar al vendedor del altavoz. Segundo objeto: `ewallet` - Introduzca el «ID» de la billetera que recibió cuando creó la billetera del vendedor del teléfono en su sandbox. Para los fines de esta lección de caso de uso, estamos usando ewallet_11078019438f943986c1fcfbaba05e13, que es el ID de la billetera que hemos creado en nuestro sandbox. `amount`- Introduzca 200 como el monto a pagar al vendedor del teléfono.
escrow	Introduzca verdadero para habilitar el depósito en garantía.
escrow_release_days	Ingrese 5 como el número de días antes de que los fondos del depósito en garantía se liberen automáticamente.

Crear solicitud de pago

Solicita a Rapyd que procese el pago y el pago del depósito en garantía.

Solicitud

// Request URL: POST https://sandboxapi.rapyd.net/v1/payments

// Message body:
{
        "amount": 250,
        "currency": "USD",
        "requested_currency": "USD",
        "payment_method": {
                "type": "us_debit_visa_card",
                "fields": {
                        "number": "4111111111111111",
                        "expiration_month": "10",
                        "expiration_year": "20",
                        "cvv": "123",
                        "name": "Test User"
                }
        },
        "ewallets": [
                {
                        "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                        "amount": 50
                }, {
                        "ewallet": "ewallet_11078019438f943986c1fcfbaba05e13",
                        "amount": 200
                }
        ],
        "escrow": true,
        "escrow_release_days": "5"
}

Python

from pprint import pprint

from utilities import make_request

payment_body = {
    "amount": 250,
    "currency": "USD",
    "requested_currency": "USD",
    "payment_method": {
        "type": "us_visa_card",
        "fields": {
            "number": "4111111111111111",
            "expiration_month": "10",
            "expiration_year": "20",
            "cvv": "123",
            "name": "John Doe"
        }
    },
    "ewallets": [
        {
            "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
            "amount": 50
        }, {
            "ewallet": "ewallet_11078019438f943986c1fcfbaba05e13",
            "amount": 200
        }
    ],
    "escrow": True,
    "escrow_release_days": "5"
}

create_payment_response = make_request(method='post',
                                       path='/v1/payments',
                                       body=payment_body)
pprint(create_payment_response)

Crear respuesta de pago

Veamos la respuesta.

Respuesta

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "2eb07c96-f541-43fa-bd33-3599c7ebb033"
    },
    "data": {
        "id": "payment_3b01b41950ec59d92c532974edc8f7dd",
        "amount": 250,
        "original_amount": 250,
        "is_partial": false,
        "currency_code": "USD",
        "country_code": "US",
        "status": "CLO",
        "description": "",
        "merchant_reference_id": "",
        "customer_token": "cus_30896ef7ee24397f340cc64a1f474697",
        "payment_method": "card_cf53c0452fb183a09d1fff2f16577b74",
      
//   ...
          
        "created_at": 1580986835,
      
//   ...         
      
        "paid": true,
        "paid_at": 1580986836,
        
//   ...         
          
        "ewallets": [
            {
                "ewallet_id": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                "amount": 200,
                "percent": 0,
                "released_amount": 0,
                "refunded_amount": 0
            },
            {
                "ewallet_id": "ewallet_11078019438f943986c1fcfbaba05e13",
                "amount": 50,
                "percent": 80,
                "released_amount": 0,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "us_debit_visa_card",
        "payment_method_type_category": "card",
       
 //   ...                  
          
        "escrow": {
            "id": "escrow_150c88345d2bca0a8be05e54a952cc80",
            "payment": "payment_3b01b41950ec59d92c532974edc8f7dd",
            "amount_on_hold": 250,
            "total_amount_released": 0,
            "status": "on_hold",
            "escrow_release_days": 5,
            "created_at": 1580986835,
            "updated_at": 1580986835,
            "last_payment_completion": 1580986836
        },
        "group_payment": ""
    }
}

La sección data de esta respuesta muestra que:

El amount es 250.
El currency es USD.
El objeto ewallet indica:
- El monto de 50 se retienen en depósito de garantía para el ewallet_id ewallet_090e1ef18c3aa754fd43cce9ee454858 .
- El monto de 200 se retiene en depósito de garantía para el ewallet_id ewallet_11078019438f943986c1fcfbaba05e13 .
El objeto escrow indica:
- El id es escrow_150c88345d2bca0a8be05e54a952cc80 .
- El ID del pago es payment_3b01b41950ec59d92c532974edc8f7dd.
- El amount_on_hold es 250.
- El status es on_hold.
- El escrow_release_days es 5.

Cuando solicite a Rapyd que libere los fondos al vendedor del altavoz, utilizará el ewallet_id, el id del objeto escrow y el ID del payment.

Entregar fondos a un vendedor

Decide liberar inmediatamente los fondos de USD 50 (dólares estadounidenses) al vendedor del altavoz.

Para eso, utilizará Libere fondos del depósito en garantía con los siguientes parámetros:

Descripción de los parámetros de ruta

Parámetro de ruta	Descripción
payment	Introduzca el ID del pago («id») que recibió cuando creó el pago en su sandbox. Para los fines de esta lección de caso de uso, estamos usando payment_3b01b41950ec59d92c532974edc8f7dd, que es el ID del pago que creamos en nuestro sandbox.
escrow	Introduzca el ID del depósito en garantía («id») que recibió cuando creó el pago en su sandbox. Para los fines de esta lección de caso de uso, estamos usando escrow_150c88345d2bca0a8be05e54a952cc80, que es el ID del depósito en garantía que creamos en nuestro sandbox.

Descripción de los parámetros del cuerpo

Parámetro del cuerpo	Descripción
ewallets	Introduzca una matriz de «ewallets» con un objeto que tenga los siguientes campos: `ewallet` - Introduzca el «id» del Rapyd Wallet que recibió cuando creó la billetera del vendedor del altavoz en su sandbox. Para los fines de esta lección de caso de uso, estamos usando ewallet_090e1ef18c3aa754fd43cce9ee454858, que es el ID de la billetera que hemos creado en nuestro sandbox. `amount` - Introduzca 50 como el monto a entregar al vendedor del altavoz.

Parámetro del cuerpo

Descripción

ewallets

Introduzca una matriz de «ewallets» con un objeto que tenga los siguientes campos:

ewallet - Introduzca el «id» del Rapyd Wallet que recibió cuando creó la billetera del vendedor del altavoz en su sandbox. Para los fines de esta lección de caso de uso, estamos usando ewallet_090e1ef18c3aa754fd43cce9ee454858, que es el ID de la billetera que hemos creado en nuestro sandbox.
amount - Introduzca 50 como el monto a entregar al vendedor del altavoz.

Solicitud de liberar fondos de un depósito en garantía

Solicite a Rapyd que libere los fondos a un vendedor.

Solicitud

// Request URL: POST https://sandboxapi.rapyd.net/v1/payments/payment_3b01b41950ec59d92c532974edc8f7dd/escrows/escrow_150c88345d2bca0a8be05e54a952cc80/escrow_releases

// Message body:
{
"ewallets": [
                {
                        "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                        "amount": 50
                }
  ]
}

.NET Core

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string payment = "payment_3b01b41950ec59d92c532974edc8f7dd";
                string escrow = "escrow_150c88345d2bca0a8be05e54a952cc80";

                var requestObj = new
                {

                    ewallets = new Object[]
                    {
                        new {
                            ewallet =  "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                            amount = 50
                        },
                    }
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/payments/{payment}/escrows/{escrow}/escrow_releases", request);

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

PHP

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

$body = [
    array(
        "ewallet" => "ewallet_090e1ef18c3aa754fd43cce9ee454858",
        "amount" => 50
    )
];

try {
    $object = make_request('post', '/v1/payments/payment_3b01b41950ec59d92c532974edc8f7dd/escrows/escrow_150c88345d2bca0a8be05e54a952cc80/escrow_releases', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

release_funds_body = {
    "ewallets": [
        {
            "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
            "amount": 50
        }
    ]
}
release_funds_response = make_request(method='post',
                                      path='/v1/payments/payment_3b01b41950ec59d92c532974edc8f7dd/escrows/escrow_150c88345d2bca0a8be05e54a952cc80/escrow_releases',
                                      body=release_funds_body)
pprint(release_funds_response)

Respuesta de liberar fondos de un depósito en garantía

Veamos la respuesta.

Respuesta

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "8338da6d-997c-41fb-97ef-def18c133224"
    },
    "data": {
        "id": "escrow_150c88345d2bca0a8be05e54a952cc80",
        "payment": "payment_3b01b41950ec59d92c532974edc8f7dd",
        "amount_on_hold": 250,
        "total_amount_released": 50,
        "status": "released",
        "escrow_release_days": 5,
        "escrow_releases": {
            "data": [
                {
                    "id": "er_ac023aae3b13b0e74ad64c876b1034dd",
                    "amount": 50,
                    "trigger": "event",
                    "proportional_release": false,
                    "ewallets": [
                        {
                            "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                            "amount": 250
                        }
                    ],
                    "created_at": 1580987535
                }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/payments/payment_3b01b41950ec59d92c532974edc8f7dd/escrows/escrow_150c88345d2bca0a8be05e54a952cc80/escrow_releases"
        },
        "created_at": 1580986835,
        "updated_at": 1580987535,
        "last_payment_completion": 1580986836
    }
}

La sección datos de esta respuesta muestra que:

El amount_on_hold es 250.
El objeto escrow_releases indica:
- Una cantidad de USD 50 fue liberado para el ewallet_id ewallet_090e1ef18c3aa754fd43cce9ee454858
El escrow_release_days es 5.

Después de cinco días, USD 50 se libera automáticamente a ewallet_11078019438f943986c1fcfbaba05e13. Para obtener una lista de todas las liberaciones de fondos de este depósito en garantía, ver Listar liberaciones de depósito en garantía.

En esta sección:

Documentación

Administrar el depósito en garantía

Retener un pago en depósito en garantía

Flujo de trabajo de varias liberaciones para un vendedor

Certificación PCI

Paso 1: Procesar el pago en depósito en garantía

Paso 2: Liberar los fondos en depósito en garantía

Estados de depósito en garantía

Cómo funciona la administración del depósito en garantía

Prerrequisitos

Buscar métodos de pago disponibles

Solicitud de lista de métodos de pago por país

Respuesta de la lista de métodos de pago por país

Encontrar los campos obligatorios para el método de pago

Solicitud de obtener campos obligatorios del método de pago

Respuesta de obtener campos obligatorios del método de pago

Crear el pago y el depósito en garantía

Crear solicitud de pago

Crear respuesta de pago

Entregar fondos a un vendedor

Solicitud de liberar fondos de un depósito en garantía

Respuesta de liberar fondos de un depósito en garantía

Resultados de la búsqueda