dapp
CashOut

Con la integración de Cash Out, tu Medio de Pago adquirirá la capacidad de generar referencias Cash Out en forma de referencia numérica que tus usuarios podrán usar para realizar retiros de efectivo en los puntos de venta de la red Cash Out by dapp®.

En esta documentación encontrarás toda la información necesaria para:

  • Generación de referencia
  • Cancelación de referencia
  • Recibir notificación de Cash Out

Te recomendamos ir a la sección de Glosario antes de continuar para que te familiarices con los términos que usamos en esta documentación.

En caso de tener alguna duda, estaremos felices de ayudarte a través del botón de contacto que se encuentra en cada una de las secciones de esta documentación.

Paso a Paso
Ambientes

dapp® cuenta con un sandbox para poder realizar pruebas durante el desarrollo.
Las URL base para cada ambiente son las siguientes:


Sandbox:

https://wallets-sandbox.dapp.mx/v2/


Producción:

https://wallets.dapp.mx/v2/
Autenticación

dapp® utiliza "Basic Access Authentication" para el REST API, usando el API KEY como usuario y dejando el password vacío.


curl --location --request GET 'https://wallets-sandbox.dapp.mx/v2' \
--header 'Authorization: Basic eW91ci1hcGkta2V5Og=='
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic eW91ci1hcGkta2V5Og==");
Request request = new Request.Builder()
  .url("https://wallets-sandbox.dapp.mx/v2")
  .method("GET", null)
  .addHeader("Authorization", "Basic eW91ci1hcGkta2V5Og==")
url = "https://wallets-sandbox.dapp.mx/v2"

payload={}
headers = {
  'Authorization': 'Basic eW91ci1hcGkta2V5Og==',
}

response = requests.request("GET", url, headers=headers, data=payload)
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://wallets-sandbox.dapp.mx/v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic eW91ci1hcGkta2V5Og=="
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
Generación de referencia

Para generar una referencia numérica con la que el usuario podrá realizar una transacción de Cash In o Cash Out se debe usar el siguiente endpoint.

/cashout/references

Url completa en sandbox:
https://wallets-sandbox.dapp.mx/v2/cashout/references

Método HTTP
POST

Parámetros aceptados:

Parámetro

Descripción

Requerido u opcional

amount

Monto de la referencia.

Requerido

expiration_minutes

Tiempo de expiración de la referencia. Por default toma el valor de un día.

Opcional

name

Nombre del usuario.

Opcional

email

Correo electrónico del usuario.

Opcional

phone

Teléfono del usuario.

Opcional



Ejemplos de código
curl --location 'https://wallets-sandbox.dapp.mx/v2/cashout/references' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg==' \
--data-raw '{
    "amount": 100.0,
    "expiration_minutes": 60,
    "name": "User name",
    "email": "user@mail.com",
    "phone": "1234567890"
}'
var client = new RestClient("https://wallets-sandbox.dapp.mx/v2/cashout/references");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg==");
var body = @"{" + "\n" +
@"    ""amount"": 100.0," + "\n" +
@"    ""expiration_minutes"": 60," + "\n" +
@"    ""name"": ""User name""," + "\n" +
@"    ""email"": ""user@mail.com""," + "\n" +
@"    ""phone"": ""1234567890""" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
    OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"amount\": 100.0,\n    \"expiration_minutes\": 60,\n    \"name\": \"User name\",\n    \"email\": \"user@mail.com\",\n    \"phone\": \"1234567890\"\n}");
Request request = new Request.Builder()
  .url("https://wallets-sandbox.dapp.mx/v2/cashout/references")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg==")
  .build();
Response response = client.newCall(request).execute();
import requests
import json

url = "https://wallets-sandbox.dapp.mx/v2/cashout/references"

payload = json.dumps({
  "amount": 100,
  "expiration_minutes": 60,
  "name": "User name",
  "email": "user@mail.com",
  "phone": "1234567890"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg=='
}
response = requests.request("POST", url, headers=headers, data=payload)

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://wallets-sandbox.dapp.mx/v2/cashout/references',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "amount": 100.0,
    "expiration_minutes": 60,
    "name": "User name",
    "email": "user@mail.com",
    "phone": "1234567890"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
Respuesta de ejemplo:
{ "rc": 0, "msg": "Ok", "data": { "reference": "21004040000000000090", "creation_date": "2020-11-04T18:13:46.613399-06:00", "expiration_date": "2020-11-04T19:13:46.613399-06:00", "amount": 100.0, "currency": "MXN" } }
Parámetros devueltos:

Parámetro

Descripción

reference

Número de referencia que presentará el usuario al cajero para realizar la operación.

creation_date

Indica la fecha de creación.

expiration_date

Especifica la fecha de vencimiento de la referencia.

amount

Indica el monto de la referencia.

currency

Especifica la moneda.


Cancelación de referencia

Para cancelar una referencia numérica se debe usar el siguiente endpoint

/cashout/references/{reference_number}

Url completa en sandbox:
https://wallets-sandbox.dapp.mx/v2/cashout/references/{reference_number}

Método HTTP
DELETE

Ejemplo completo de URL:
https://wallets-sandbox.dapp.mx/v2/references/xxxxxxxxx

Ejemplos de código
curl --location --request DELETE 'https://wallets-sandbox.dapp.mx/v2/cashout/references/{reference_number}' \
--header 'Authorization: Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg=='
var client = new RestClient("https://wallets-sandbox.dapp.mx/v2/cashout/references/{reference_number}");
client.Timeout = 60;
var request = new RestRequest(Method.Delete);
request.AddHeader("Authorization", "Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg==");
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://wallets-sandbox.dapp.mx/v2/cashout/references/{reference_number}")
  .method("DELETE", body)
  .addHeader("Authorization", "Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg==")
  .build();
Response response = client.newCall(request).execute();
import requests

url = "https://wallets-sandbox.dapp.mx/v2/cashout/references/{reference_number}"

payload = {}
headers = {
  'Authorization': 'Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg=='
}

response = requests.request("DELETE", url, headers=headers, data=payload)
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://wallets-sandbox.dapp.mx/v2/cashout/references/{reference_number}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic MjY3NDMyMTktOGIxNi00ZWI3LTk4Y2ItMzRkM2I2ZjEzNzlkOg=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
Respuesta de ejemplo:
{ "rc": 0, "msg": "Ok" }
Nota:

no es necesario crear una estructura body, con el método y la URL configurada, la petición puede ser enviada.


Recibir notificación de Cash Out

El wallet debe exponer un servicio que acepte peticiones donde Dapp le confirmará que se ha realizado una transacción de Cash In.

Petición de ejemplo:
{ "id": "2c2725ca-eada-426a-b928-8bb851128059", "reference": "20004042284511626341" "amount": 100.0, "fee": 10.0, "total": 110.0, "currency": "MXN", "merchant": "Farmacias del Ahorro", "date": "2020-11-04T18:13:46.613399-06:00", "refunded": false, "security": { "key": "2c2725caeada426ab9288bb851128059", "version": 1, "signature": "L1Xb1RFcDjai0QB7ZZT0+iQC4VyIoF861FBFPlU4z2PEhwkUa1YYGIbHqSk5kyXzReimDkwedhbSldBKAJFrUlGb6mhepGszb4hCNLTcPnKwZIT+vQWOQmx6aXjIHE27qQe537NNfODWF26RBgCDonQQjHKfaUrKYWaCy/kT2bWh4uIedaInmEfuEf9/rnPVY8pJXHAkkFSXIwb8f2+PdNyciJACb5TAYiTRortXNKpAteeo9SFiW83o7I4FKlfpaFf+R37piyRrdS6/McnOLOHYx6pQVzuVOeyJZ1ea0m0FD2kRf/wPAGazqT7ix47mO206IEt5+tHIxHPgBKoRbQ==", } }
Parámetros devueltos:

Parámetro

Descripción

reference

Indica el número de referencia.

amount

Indica el monto de la referencia.

fee

Indica el monto de la comisión.

total

Específica el monto total del pago.

currency

Especifica la moneda.

merchant

Indica el nombre del comercio donde se realizó la operación.

date

Indica la fecha de la transacción.

refunded

Especifica si la transacción ha sido reembolsada o no.

El JSON de la petición contiene una firma digital como método de autenticación. El nombre de la llave utilizada para la firma se envía dentro del campo key con un hash MD5. La firma consiste en una cadena formada por los campos id, reference, amount, fee, currency, refunded, date separados por pipes con una función hash SHA-512.

Ejemplo de cadena antes del hash.
2c2725ca-eada-426a-b928-8bb851128059|20004042284511626341|100.0|10.0|MXN|false|2020-11-04T18:13:46.613399-06:00

Una vez que el wallet valide la veracidad de la firma y confirme que el usuario cuenta con los fondos suficientes para realizar la operación, deberá regresar como respuesta un objeto JSON con los campos rc y msg.

Valores predefinidos para respuesta.

rc

msg

0

Operación exitosa.

-10

Referencia inválida.

-20

Error de validación.

-30

Servicio no disponible.

-40

Fondos insuficientes.

-99

Otro.


Glosario

Te dejamos aquí algunos términos relevantes definidos para facilitar la lectura y entendimiento de nuestras documentaciones.


Código de cobro:
Es el identificador único asignado a una transacción de cobro generada por un comercio y que está asociado a ciertos parámetros específicos como Nombre del Comercio, Monto, Moneda, Fecha, Lugar y Hora, entre otros. Un código de cobro puede ser representado como un Código QR para ser escaneado por el cliente, o ser transferido a un dispositivo móvil a través de un deep link o una notificación push.


Código QR:
Un código de respuesta rápida (o Código QR) es una representación gráfica bidimensional de una cadena de texto generado por que generalmente se asocia a un código de cobro.


Código QR dinámico:
Es aquél Código QR asociado a un solo código de cobro y a una sola transacción única y diferenciable. Sus parámetros pueden tomar valores distintos en cada transacción. Cada Código QR se verá distinto a los demás ya que representará una cadena de texto distinta.


Código QR estático:
Es aquél Código QR que luce permanentemente igual ya que siempre representa una misma cadena de texto. Este tipo de códigos son útiles cuando los parámetros asociados a los códigos de cobro son siempre iguales. Dado que la representación gráfica no cambia, estos códigos pueden ser impresos y usados múltiples veces para pagar un mismo código de cobro.


Referencia Cash in:
Es un código alfanumérico asociado a una transacción de pago en efectivo, ya sea para realizar un depósito de efectivo, para realizar un pago de servicios, para realizar el pago en efectivo de una orden de comercio electrónico, o cualquier otra operación equivalente. Las referencias Cash In están siempre asociadas a parámetros específicos como Monto, Fecha, Hora, entre otros, y son generadas a petición del usuario cuando este desea realizar una operación de este tipo.


Súmate a la revolución.
Intégrate ahora.

Súmate a la revolución.
Intégrate ahora.

Quiero Integrarme
Es la forma de contacto, ingresa un correo correcto
El número debe de ser de al menos 10 dígitos







Olvidé mi contraseña