---
updatedAt: 2026-09-16T10:59:29.000Z
agentTools:
projectIndex: https://readme.floid.io/llms.txt
---
# Payin Perú
La API de Payinde Floid Perú permite recibir pagos cuenta a cuenta utilizando distintos **medios de pago locales**, a través de un**payment\_url embebible**.
Con esta versión es posible:
* Realizar pagos por transferencia bancaria
* Realizar pagos vía Yape
* Realizar pagos vía Pago de Servicios (CIP)
* Mostrar todos los métodos en un solo widget
El response es siempre unificado.
# 1️⃣ Crear Pago (Create Payin)
## Endpoint
POST {{HOST}}/pe/payments/create
## Autenticación
Authorization: Bearer YOUR\_API\_TOKEN\
Content-Type: application/json
### Request
```
{
"amount": 1000,
"currency": "PEN",
"type": "all",
"default": "yape",
"webhook_url": "https://webhook.site/..."
}
```
# 2️⃣ Nuevo campo `type`
Se incorpora el campo opcional:
[block:parameters]
{
"data": {
"h-0": "Parámetro",
"h-1": "Descripción del Campo",
"h-2": "Ejemplo",
"h-3": "Validación",
"h-4": "Tipo",
"0-0": "amount",
"0-1": "Monto de la transacción o cantidad",
"0-2": "300",
"0-3": "Debe ser un número no negativo",
"0-4": "float",
"1-0": "currency",
"1-1": "Moneda. Posibles valores: \n`PEN` \n`USD`",
"1-2": "PEN",
"1-3": "",
"1-4": "string",
"2-0": "type",
"2-1": "Método de pago (bank_transfer, yape, services)",
"2-2": "all",
"2-3": "",
"2-4": "string",
"3-0": "default",
"3-1": "Método de pago por defecto",
"3-2": "yape",
"3-3": "",
"3-4": "string"
},
"cols": 5,
"rows": 4,
"align": [
null,
null,
null,
null,
null
]
}
[/block]
## Valores permitidos
* "bank\_transfer"
* "yape"
* "services"
* "all"
* (próximamente) "qr\_payment"
En caso de que type=all el cliente puede incluir el parámetro default indicando el servicio que se despliegue por defecto, por ejemplo si default es yape, entonces el widget se mostrará todos los medios de pago pero por defecto el yape.
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/8b2998d05a4514809ad8101b8c1a8b35639c4f191a9a13b8be73972cf207eeb4-image.png",
null,
""
],
"align": "center",
"sizing": "200px"
}
]
}
[/block]
# 3️⃣ Comportamiento del Widget
## 🔹 Sin `type` (compatibilidad backward)
* Se asume modo `all`
* El widget muestra:
* Bank Transfer
* Yape
* Pago de Servicios (CIP)
* Método inicial por defecto: `bank_transfer`
## 🔹 type = "all"
Permite mostrar todos los métodos y definir cuál se muestra primero.
```json
{
"amount": 1000,
"currency": "PEN",
"type": "all",
"default": "yape",
"webhook_url": "https://webhook.site/..."
}
```
Con el siguiente response
```
{
"code": 200,
"payment_token": "fca6b40e-8a25-47f7-a085-868da5fcee1d",
"payment_url": "https://payments.floid.app/?id=fca6b40e-8a25-47f7-a085-868da5fcee1d"
}
```
Si `default` no se envía → inicia en `bank_transfer`.
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/5bf4901ff4c8e9219faf46a6db51cfb57a9f2fc265354d86b0fe05231b1a3ffc-image.png",
null,
""
],
"align": "center",
"sizing": "250px"
}
]
}
[/block]
## 🔹 type = "bank\_transfer"
```json
{
"amount": 1000,
"currency": "PEN",
"type": "bank_transfer",
"webhook_url": "https://webhook.site/..."
}
```
## 🔹 type = "yape"
```json
{
"amount": 1000,
"currency": "PEN",
"type": "yape",
"phone": "5121312321",
"name": "Andrés Poblete",
"webhook_url": "https://webhook.site/..."
}
```
El backend genera un `document_id` que se embebe en el deeplink de Yape\
como:
consumerCode=``el cual permite realizar el pago desde la app de yape
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/877d81b20e642d19273dfdd4ad6e330c8388f32666731dbb3944f5fc8f7fce7d-image.png",
null,
""
],
"align": "center",
"sizing": "250px"
}
]
}
[/block]
El usuario al ingresar al link, será redirigido a la app de yape mostrando el recibo pendiente asociado a Floid Pago. Una vez realizado el pago el widget mostrará que el pago ha sido realizado exitosamente
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/88676a9c8e01d63063d07df76f9e1c72b7b8fa293eaa2e5656e04a97d64e744b-image.png",
null,
""
],
"align": "center",
"sizing": "500px"
}
]
}
[/block]
## 🔹 type = "services" (CIP)
Pago de servicios via banco BCP
```json
{
"amount": 1000,
"currency": "PEN",
"type": "services",
"webhook_url": "https://webhook.site/..."
}
```
El widget mostrará instrucciones y el código CIP.
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/b2b7edf5fb2fbafbf715dfb8ff230ec50b567f8712e322e9144762fc087f96dc-image.png",
null,
""
],
"align": "center",
"sizing": "250px"
}
]
}
[/block]
# 4️⃣ Response Unificado
```json
{
"code": 200,
"payment_token": "c0d5a05c-19ed-4282-9ed7-9ee722d3b3d0",
"payment_url": "https://payments.floid.app/?id=c0d5a05c-19ed-4282-9ed7-9ee722d3b3d0"
}
```
Dentro del request es posible enviar campos opcionales:
***Opcionales***: Listados de campos opcionales al request para adecuaciones custom.
[block:parameters]
{
"data": {
"h-0": "Parámetro",
"h-1": "Descripción del Campo",
"h-2": "Ejemplo",
"h-3": "Validación",
"h-4": "Tipo",
"0-0": "consumer_id",
"0-1": "DNI/ID del usuario. Si se indica, no se permitirá cambiar en el widget y por lo tanto el pago deberá ser realizado por una cuenta bancaria asociada a este DNI/ID.",
"0-2": "12345678",
"0-3": "7 u 8 dígitos",
"0-4": "string",
"1-0": "consumer_id_type",
"1-1": "Tipo de documento del usuario. Posibles valores: \n`dni` \n`ce` (Carné de Extranjería) \n`pas` (Pasaporte)",
"1-2": "dni",
"1-3": "",
"1-4": "",
"2-0": "store_credentials",
"2-1": "Variable para permitir el guardado o no de la credenciales.",
"2-2": "false",
"2-3": "",
"2-4": "boolean",
"3-0": "token_password",
"3-1": "String devuelto si se inició un pago con `store_credentials: true`.",
"3-2": "def50200c5cfd43dg4...",
"3-3": "",
"3-4": "string",
"4-0": "sandbox",
"4-1": "Para crea un pago en ambiente de prueba",
"4-2": "false",
"4-3": "",
"4-4": "boolean",
"5-0": "redirect_url",
"5-1": "URL a la que se redirigirá al cliente cuando el proceso haya finalizado.",
"5-2": "",
"5-3": "URL válida",
"5-4": "string",
"6-0": "webhook_url",
"6-1": "URLa la que se enviará el resultado de la operación.",
"6-2": "",
"6-3": "URL válida",
"6-4": "",
"7-0": "expiration_date",
"7-1": "Hora y fecha de expiración del flujo. En caso de no incluirse, el tiempo de expiración por defecto es de 24 horas desde su creación. El formato debe ser \n`YYYY-MM-DD hh:mm:ss`",
"7-2": "2030-01-01 10:00:30",
"7-3": "fecha",
"7-4": "string",
"8-0": "custom",
"8-1": "Información que se devuelve al webhook al finalizar la operación",
"8-2": "",
"8-3": "",
"8-4": "string",
"9-0": "bank",
"9-1": "Define el banco a utilizar para realizar la transferencia. Posibles valores: \n`banco_bcp_personas transferencia_bancaria_personas\n`",
"9-2": "",
"9-3": "",
"9-4": "string",
"10-0": "recipient",
"10-1": "Datos del destinatario (ver tabla datos recipient)",
"10-2": "",
"10-3": "",
"10-4": "object"
},
"cols": 5,
"rows": 11,
"align": [
null,
null,
null,
null,
"left"
]
}
[/block]
# 5️⃣ Estados del Pago
* PENDING
* SUCCESS
* SUCCESS\_OVERPAID (solo aplica a bank\_transfer)
* SUCCESS\_UNDERPAID (solo aplica a bank\_transfer)
* EXPIRED
* CANCELED
# 6️⃣ Webhooks
Cuando el estado cambia, Floid enviará un JWT al `webhook_url`\
configurado con:
* payment\_token
* status
* transfer\_data
* amount
* step
* payment\_id
* custom (si aplica)
# 7️⃣ Sandbox
```json
{
"amount": 1000,
"currency": "PEN",
"sandbox": 1,
"webhook_url": "https://webhook.site/..."
}
```
# 8 Consulta estado de pago
Para poder consultar el estado de un pago, se puede utilizar el método / check a través del payment token generado utilizando el endpoint
```
/pe/payments/check
```
Request
```
{
"payment_token":"82d11bb7-58dd-4b9b-88c9-b16b579d805c"
}
```
Con el siguiente response
```
{
"step": "FINISHED",
"bank": "transferencia_yape_personas",
"response": {
"code": 200,
"status": "SUCCESS",
"message": "Pago confirmado por backend_polling",
"status": "PAID",
"amount": "154.00",
"expected_amount": "154.00"
},
"date": "2026-04-17 11:57:34",
"session_data": {
"verified_by": "backend_polling"
}
}
]
```