Crear un Payout

El API de Payouts permite solicitar múltiples pagos utilizando el saldo disponible en su cuenta.

Solicitud del Payout

Este método le permite solicitar uno o más Payouts utilizando los fondos depositados en su cuenta.

URL del Request

Debe invocar un request POST a las siguientes URL de acuerdo con sus necesidades.

  • Producción: https://payout-api.bamboopayment.com/api/payout
  • stage: https://payout-api.stage.bamboopayment.com/api/payout

Parámetros del Request

La siguiente tabla muestra los parámetros obligatorios y opcionales para crear Payouts para todos los países.

CampoTipo¿Obligatorio?Descripción
countrystring(2)SíCódigo ISO del país en formato ISO 3166-2.
Listado de países disponibles de Payouts.
amountintegerSíMonto del Payout, el formato tiene dos dígitos decimales.
Ejemplo 100 => $ 1,00.
currencystring(3)SíCódigo ISO de la moneda. Esta moneda debe coincidir con la configurada en su cuenta.
Consulte aquí la lista de monedas.
reasonstringNoDescripción del Payout.
destinationCurrencystring(3)SíCódigo ISO de la moneda en la que el beneficiario recibirá el pago. Este parámetro no es necesario para el modelo USD2L, y el sistema utilizará por defecto la moneda del país de destino cuando no se envíe.
Esta moneda debe cumplir el modelo de su cuenta.
Por ejemplo:
  • Para USD2L, el parámetro currency debe ser USD, y el parámetro destinationCurrency es optativo.
  • Para USD2USD, tanto currency como destinationCurrency deben ser USD.
  • Para L2L, currency y destinationCurrency deben ser la moneda del país elegido.

Consulte aquí la lista de monedas.
referencestringSíIdentificador único del Payout definido por usted.
Asegúrese de que sea único.
typeintegerSíTipo de Payout. Asigne cualquiera de los siguientes valores:
  • 1 para Efectivo
  • 2 para Transferencia Bancaria
  • 3 para Wallet
  • 4 para Transferencias Bancarias Instantáneas en Brasil
InstantPaymentData → PixDocument stringSí1El número CPF/CNPJ del beneficiario configurado como clave PIX.
El número de dígitos para CPF debe ser 11 y CNPJ debe ser 14.
InstantPaymentData → PixEmailstringSí1La dirección de correo electrónico del beneficiario configurado como clave PIX.
Este parámetro debe ser una dirección de correo electrónico válida.
InstantPaymentData → PixPhonestringSí1El número de teléfono del beneficiario configurado como clave PIX.
El número debe empezar por +55.
InstantPaymentData → PixRandomstringSí1La clave aleatoria que el beneficiario ha generado como clave PIX.
notification_UrlstringNoWebhook para notificar el resultado del Payout. Para más información sobre la configuración de este webhook, consulte este artículo.
payee → FirstNamestringSí3Nombre del Beneficiario.
payee → lastNamestringSí3Apellido del Beneficiario.
payee → companyNamestringSí3Nombre de la empresa.
payee → emailstringNoDirección de correo electrónico del Beneficiario.
payee → phonestringNoNúmero de teléfono del Beneficiario.
payee → addressstringNoDirección del Beneficiario.
payee → document → typestringSíTipo de documento del Beneficiario.
Encuentre la lista de documentos aquí.
payee → document → numberstringSíNúmero de documento del Beneficiario.
payee → bankaccount → numberstringSí2Número de cuenta del Beneficiario.
Tenga en cuenta las siguientes consideraciones:
  • Para Argentina, configure the CBU/CVU.
  • Para México, configure el número CLABE.
payee → bankaccount → typeintegerSí2Tipo de cuenta del Beneficiario. Asigne 1 para Cuenta corriente y 2 para Cuenta de ahorros.
payee → bankaccount → codebankstringSí2Código del banco del Beneficiario.
Puede obtener la lista de bancos de un país determinado utilizando el método Obtener listado de bancos. También, puede encontrar el listado de bancos.

1 Sólo aplica para Brasil usando Transferencia Bancaria Instantánea. En caso contrario, el objeto payee.InstantPaymentData y sus parámetros no deben estar presentes en el request.
2 Cuando utilice Transferencias Bancarias, estos parámetros son obligatorios para TODOS los países. Para Transferencias Bancarias Instantáneas en Brasil, el objeto payee.bankaccount y sus parámetros no deben estar presentes en el request.
3 Son mandatorios los campos firstName y lastName para persona física y companyName para persona jurídica (empresa). Si se envía un payout para empresa solo se tiene que completar el campo companyName, y si se envía un payout a una persona física solo se tienen que completar los campos firstName y lastName.
Importante: Los campos firstName y lastName no soportan ni números ni caracteres especiales, solo letras. El campo companyName sí acepta todo tipo de caracteres alfanuméricos.

Ejemplo del Request

Consulte la pestaña correspondiente de acuerdo con el país del beneficiario.


Argentina: De USD a ARS:

{
    "country": "AR",
    "amount": 1000,
    "currency": "USD",
    "destinationCurrency":"ARS",
    "reason": "string",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Sara",
      "lastName": "Jáquez",
      "email": "sarasouez@mail.com",
      "phone": "099999999",
      "address": "Francisco  51 Gral. Ximena, AR-H 0376",
      "document": {
        "type": "CUIL",
        "number": "12345678901"
      },
      "bankAccount": {
        "number": "0000053600000000000566",
        "type": 1,
        "codeBank": "7"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Argentina: De ARS a ARS:

{
    "country": "AR",
    "amount": 1000,
    "currency": "ARS",
    "reason": "string",
    "destinationCurrency":"ARS",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Sara",
      "lastName": "Jáquez",
      "email": "sarasouez@mail.com",
      "phone": "099999999",
      "address": "Francisco  51 Gral. Ximena, AR-H 0376",
      "document": {
        "type": "CUIL",
        "number": "12345678901"
      },
      "bankAccount": {
        "number": "0000053600000000000566",
        "type": 1,
        "codeBank": "7"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Como se mencionó anteriormente, el objeto payee.bankaccount no debe estar presente en el request. Por lo tanto, al utilizar Transferencias Bancarias Instantáneas es necesario enviarlo de la siguiente manera:

Brasil: De USD a BRL:

{
    "country": "BR",
    "amount": 100,
    "currency": "USD",
    "destinationCurrency":"BRL",
    "reason": "string",
    "reference": "PayOut34",
    "type": 4,
    "InstantPaymentData": {
      "PixEmail":"tcosta@mail.com" // Can also be PixDocument, PixPhone, or PixRandom
    },
    "payee": {
      "firstName": "Tiago",
      "lastName": "Costa",
      "email": "tcosta@mail.com",
      "phone": "92799322",
      "address": "55489-272, Travessa Eduardo, 90 Esteves do Norte - CE",
      "document": {
        "type": "CPF",
        "number": "54562271779"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Brasil: BRL a BRL

{
    "country": "BR",
    "amount": 100,
    "currency": "BRL",
    "destinationCurrency":"BRL",
    "reason": "string",
    "reference": "PayOut34",
    "type": 4,
    "InstantPaymentData": {
      "PixEmail":"tcosta@mail.com" // Can also be PixDocument, PixPhone, or PixRandom
    },
    "payee": {
      "firstName": "Tiago",
      "lastName": "Costa",
      "email": "tcosta@mail.com",
      "phone": "92799322",
      "address": "55489-272, Travessa Eduardo, 90 Esteves do Norte - CE",
      "document": {
        "type": "CPF",
        "number": "54562271779"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Chile: USD a CLP

{
    "country": "CL",
    "amount": 1000,
    "currency": "USD",
    "destinationCurrency":"CLP",
    "reason": "string",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Mercedes",
      "lastName": "Garrido",
      "email": "merceddo@mail.com",
      "phone": "099999999",
      "address": "Camino Franco, 13, Atico 4, 93631, L Garay",
      "document": {
        "type": "CI",
        "number": "26068762K"
      },
      "bankAccount": {
        "number": "1234567890123450",
        "type": 1,
        "codeBank": "1"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Chile: CLP a CLP

{
    "country": "CL",
    "amount": 1000,
    "currency": "CLP",
    "destinationCurrency":"CLP",
    "reason": "string",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Mercedes",
      "lastName": "Garrido",
      "email": "merceddo@mail.com",
      "phone": "099999999",
      "address": "Camino Franco, 13, Atico 4, 93631, L Garay",
      "document": {
        "type": "CI",
        "number": "26068762K"
      },
      "bankAccount": {
        "number": "1234567890123450",
        "type": 1,
        "codeBank": "1"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Colombia: USD a COP

{
    "country": "CO",
    "amount": 100,
    "currency": "USD",
    "destinationCurrency":"COP",
    "reason": "string",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Diego",
      "lastName": "Silva",
      "email": "dsilva@mail.com",
      "phone": "099999999",
      "address": "Cra 23 # 123-45 Apto 601",
      "document": {
        "type": "CC",
        "number": "11111111"
      },
      "bankAccount": {
        "number": "2288",
        "type": 1,
        "codeBank": "1007"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Colombia: COP a COP

{
  "country": "CO",
  "amount": 100,
  "currency": "COP",
  "reason": "string",
  "destinationCurrency":"COP",
  "reference": "PayOut34",
  "type": 2,
  "payee": {
    "firstName": "Diego",
    "lastName": "Silva",
    "email": "dsilva@mail.com",
    "phone": "099999999",
    "address": "Cra 23 # 123-45 Apto 601",
    "document": {
      "type": "CC",
      "number": "11111111"
    },
    "bankAccount": {
      "number": "2288",
      "type": 1,
      "codeBank": "1007"
    }
  },
  "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

México: USD a MXN

{
    "country": "MX",
    "amount": 1000,
    "currency": "USD",
    "destinationCurrency":"MXN",
    "reason": "string",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Rubén",
      "lastName": "Torres",
      "email": "rubentres@mail.com",
      "phone": "01 55 5601 7965",
      "address": "Coyoacan 2000",
      "document": {
        "type": "CURP",
        "number": "OEAF771012HMCRGR09"
      },
      "bankAccount": {
        "number": "123456789012345678",
        "type": 1,
        "codeBank": "2"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

México: MXN a MXN

{
    "country": "MX",
    "amount": 1000,
    "currency": "MXN",
    "reason": "string",
    "destinationCurrency":"MXN",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Rubén",
      "lastName": "Torres",
      "email": "rubentres@mail.com",
      "phone": "01 55 5601 7965",
      "address": "Coyoacan 2000",
      "document": {
        "type": "CURP",
        "number": "OEAF771012HMCRGR09"
      },
      "bankAccount": {
        "number": "123456789012345678",
        "type": 1,
        "codeBank": "2"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Perú: USD a PEN

{
  "country": "PE",
  "amount": 1000,
  "currency": "USD",
  "destinationCurrency":"PEN",
  "reason": "string",
  "reference": "PayOut34",
  "type": 2,
  "payee": {
    "firstName": "Ornela",
    "lastName": "Olivera",
    "email": "ornelera@mail.com",
    "phone": "099999999",
    "address": "Cl. Jesús Bueno # 64 Dpto. 229",
    "document": {
      "type": "DNI",
      "number": "12345678"
    },
    "bankAccount": {
      "number": "11487349",
      "type": 1,
      "codeBank": "2"
    }
  },
  "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Perú: PEN a PEN

{
  "country": "PE",
  "amount": 1000,
  "currency": "PEN",
  "reason": "string",
  "destinationCurrency":"PEN",
  "reference": "PayOut34",
  "type": 2,
  "payee": {
    "firstName": "Ornela",
    "lastName": "Olivera",
    "email": "ornelera@mail.com",
    "phone": "099999999",
    "address": "Cl. Jesús Bueno # 64 Dpto. 229",
    "document": {
      "type": "DNI",
      "number": "12345678"
    },
    "bankAccount": {
      "number": "11487349",
      "type": 1,
      "codeBank": "2"
    }
  },
  "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Perú: USD a USD

{
    "country": "PE",
    "amount": 1000,
    "currency": "USD",
    "reason": "string",
    "destinationCurrency":"USD",
    "reference": "PayOut34",
    "type": 2,
    "payee": {
      "firstName": "Ornela",
      "lastName": "Olivera",
      "email": "ornelera@mail.com",
      "phone": "099999999",
      "address": "Cl. Jesús Bueno # 64 Dpto. 229",
      "document": {
        "type": "DNI",
        "number": "12345678"
      },
      "bankAccount": {
        "number": "11487349",
        "type": 1,
        "codeBank": "2"
      }
    },
    "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Uruguay: USD a UYU

{
  "country": "UY",
  "amount": 1000,
  "currency": "USD",
  "destinationCurrency":"UYU",
  "reason": "string",
  "reference": "PayOut34",
  "type": 2,
  "payee": {
    "firstName": "Daniel",
    "lastName": "Lorenzo",
    "email": "danielzo@mail.com",
    "phone": "999999999",
    "address": "12900 Montevideo",
    "document": {
      "type": "CI",
      "number": "38067788"
    },
     "bankAccount": {
      "number": "1234567",
      "type": 2,
      "codeBank": "113"
    }
  },
  "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Uruguay: UYU a UYU

{
  "country": "UY",
  "amount": 1000,
  "currency": "UYU",
  "reason": "string",
  "destinationCurrency":"UYU",
  "reference": "PayOut34",
  "type": 2,
  "payee": {
    "firstName": "Daniel",
    "lastName": "Lorenzo",
    "email": "danielzo@mail.com",
    "phone": "999999999",
    "address": "12900 Montevideo",
    "document": {
      "type": "CI",
      "number": "38067788"
    },
        "bankAccount": {
      "number": "1234567",
      "type": 2,
      "codeBank": "113"
    }
  },
  "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Uruguay: USD a USD

{
  "country": "UY",
  "amount": 1000,
  "currency": "USD",
  "destinationCurrency": "USD",
  "reason": "string",
  "reference": "PayOut34",
  "type": 2,
  "payee": {
      "firstName": "Daniel",
      "lastName": "Lorenzo",
      "email": "danielzo@mail.com",
      "phone": "999999999",
      "address": "12900 Montevideo",
      "document": {
          "type": "CI",
          "number": "38067788"
      },
      "bankAccount": {
          "number": "1234567",
          "type": 2,
          "codeBank": "113"
      }
  },
  "notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}

Responses

  • Ok: HttpCode 200.
    Mensaje recibido correctamente, en este punto, el Payout empieza a ser procesado.

Response body

{
    "payoutId": 145,
    "status": 5,
    "statusDescription": "Received",
    "reference": "PayOut34",
    "errors": []
}

Donde:

CampoDescripción
payoutIdIdentificador interno del Payout.
statusCódigo interno del estado actual del Payout.
statusDescriptionEstado actual del Payout. Consulte este artículo para aprender más acerca de los estados de los Payouts.
referenceIdentificador único del Payout definido por usted cuando solicitó el Payout.
errorsErrores que pueden aparecer. Encuentre los posibles errores aquí.
  • BadRequest: HttpCode HttpCode 400.
    Falló la validación del mensaje y el Payout queda en estado is not created.

Response body

{
    "errors": [
        {
            "ErrorCode": "ExactLengthValidator",
            "PropertyName": "Country",
            "Message": "'Country' must be 2 characters in length. You entered 1 characters."
        }
    ],
    "statusCode": 400
}

  • Unauthorized: HttpCode 401.
    Error de autorización.

  • Conflict - Declined: HttpCode HttpCode 409.
    La validación del mensaje fue exitosa pero, el Payout queda en estado Declinado debido a reglas de negocio.

Response body

{
    "payoutId": 493945,
    "status": 8,
    "statusDescription": "Declined",
    "reference": "QA-538",
    "error": {
        "errorCode": 812,
        "message": "Declined by validation for document"
    }
}

Obtener un Payout

Este método le permite traer la información de un Payout utilizando el identificador (ID) generado o la referencia que asignó cuando solicitó el Payout.

URL del Request

Debe invocar un request GET a las siguientes URL de acuerdo con sus necesidades.

  • Producción: https://payout-api.bamboopayment.com/api/payout
  • Stage: https://payout-api.stage.bamboopayment.com/api/payout

Para obtener el Payout, incluya los siguientes endpoints de acuerdo con sus necesidades.

  • A través del ID del Payout: {{URL}}/api/payout/{{PayoutID}}
  • A través del ID de la referencia del Payout: {{URL}}/api/payout/reference/{{PayoutReference}}

Parámetros del Response

ParámetroFormatoDescripción
payoutIdlongIdentificador interno del Payout. (Máx. 19 caracteres)
referencestringIdentificador único del Payout definido por usted cuando solicitó el Payout.
isoCountrystringCódigo ISO del país en formato ISO 3166-2.
createddateFecha y hora de la solicitud del Payout.
lastUpdatedateFecha y hora de la última actualización del Payout.
statusintegerCódigo interno del estado actual del Payout.
statusDescriptionstringEstado actual del Payout. Consulte este artículo para aprender más acerca de los estados de los Payouts.
errorCodestringCódigo interno del error del Payout declinado. Encuentre los posibles errores aquí.
errorDescriptionstringDescripción del error del Payout declinado.
amountobjectValor y moneda solicitado en el Payout.
localAmountobjectValor y moneda solicitado en el Payout en moneda local.
exchangeRatenumericValor de conversión utilizado en el Payout.
payeeobjectInformación del beneficiario del Payout.

Ejemplo del Response

{
    "payoutId": 1100,
    "reference": "QA-545",
    "isoCountry": "CO",
    "created": "2023-06-02T15:15:34.475614Z",
    "lastUpdate": "2023-06-02T15:20:18.1507484Z",
    "status": 1,
    "statusDescription": "Paid",
    "errorCode": null,
    "errorDescription": null,
    "amount": {
        "value": 10.0,
        "isoCurrency": "USD"
    },
    "localAmount": {
        "value": 42843.0,
        "isoCurrency": "COP"
    },
    "exchangeRate": 4394.23,
    "payee": {
        "firstName": "Paul",
        "lastName": "Doe",
        "email": "pauld@test.com",
        "phone": "099999999",
        "address": "address",
        "document": {
            "number": "11111111",
            "type": "CC"
        }
    }
}
footer
Última modificación 20 de diciembre de 2024

© Bamboo | All rights reserved 2024