Attributes

• METHOD TYPEBank Transfer
• PAYMENTS
• PAYOUTS
• REFUNDS
• RECURRING

Introduction

Colombia Payouts is a bank payout method in Colombia processed through Davivienda bank using the Host to Host (H2H) system.

Supported Countries

• Colombia

Supported Currencies

• COP

Payout (Withdrawal) Flow

Follow these steps to perform a payout:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.

Example /createUser Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"<2-letter ISO country code>",
  "firstName":"John",
  "lastName":"Smith",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

The request registers the userTokenId (userId) in the Nuvei system, which is needed to generate a UPO in the next step.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request and include:

• userTokenId – The unique user identifier in your system.
• paymentMethodName:”apmgw_Colombia_Payouts“
• apmData class containing:
  • co_accountType
    Possible values:
    • CA – Cuenta de Ahorros
    • CC – Cuenta Corriente
    • TP – Tarjeta Prepago
    • DP – Daviplata
  • co_accountNumber (use numbers only)
  • co_accountIdentification (use numbers only)
  • co_accountIdentificationType
    Possible values:
    • CDC – Cédula de Ciudadanía
    • CDE – Cédula de Extranjería
    • NIT – Número de Identificación Tributaria
    • NIM – Nit Menores
    • PAS – Pasaporte
    • TDI – Tarjeta de Identidad
    • TSS – Tarjeta Seguro Social
  • co_accountBankCode – Customer’s bank number
• billingAddress class containing: country and email.

Example /addUPOAPM Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique customer identifier in merchant system>",
  "paymentMethodName":"apmgw_Colombia_Payouts",
  "apmData":{
    "co_accountNumber": "098100958259",
    "co_accountBankCode": "000051",
    "co_accountIdentification": "9004531884",
    "co_accountIdentificationType": "CDC",
    "co_accountType": "CA"
  },
  "billingAddress":{
    "country":"CO",
    "email":"[email protected]",
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

Example /addUPOAPM Response

{
  "userPaymentOptionId":83458468,
  "internalRequestId":553078068,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221109154215"
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example /payout DMN with status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=342197468&userid=UserToken2022&merchant_unique_id=20180327175242&customData=Jake+Test+Account&productId=&first_name=&last_name=&email=&currency=COP&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Colombia_Payouts&ID=&merchant_id=2439523627382132721&responseTimeStamp=2022-11-09.20%3A51%3A51&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=UserToken2022&userPaymentOptionId=83458468&TransactionID=711000000017962326&externalTransactionId=H2H-5035&totalAmount=15.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20221109&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=9ab1df357665fd1291d71348f74c1ba884747fdfdb55ffb37e1858f40658c574&advanceResponseChecksum=d019006b8f51ab1a18d7c5b6f913fa25da2e5f18e9b6aaffb03c8e0a9fc19d1b',

Example /payout DMN with status=DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=9&ErrCode=0&errApmCode=9&errApmDescription=%28READ++++%29NOEXISTE+PRODU.DR%2838+1112%29&errScCode=1133&errScDescription=Rejected+by+carrier.&Reason=&ReasonCode=&PPP_TransactionID=64147297038&userid=USERUNIQUEID&merchant_unique_id=merchantID&customData=Rappi+LATAM1&productId=&first_name=&last_name=&email=&currency=COP&pmDisplayName=1234565678&clientUniqueId=clientID&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=234558&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_Colombia_Payouts&ID=&merchant_id=5324005398726594376&responseTimeStamp=2024-07-08.17%3A00%3A18&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=CO4134502&userPaymentOptionId=4731890918&TransactionID=1620000000112951385&externalTransactionId=H2H-43889539&totalAmount=1.0&dynamicDescriptor=Rappi&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20240708&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22authorizationCode%22%3A%22118650%22%7D&responsechecksum=ee236c939fbe0af10e8c3519a199fab62d5a550a957dfaac0ff62350073a1d95&advanceResponseChecksum=803e0c198cd8cbfacd9ca0bdfafaaa32cf804e4085cb81180654b6808713b3b6',

Testing

Any value can be used for account number and identification number.

Manual approval from the provider’s side is required.

Appendix

The following values are accepted for co_accountBankCode: