Nequi

Home    APMs    Nequi

On this page:
Attributes
  • METHOD TYPEE-wallet
  • PAYMENTS
  • PAYOUTS
  • REFUNDS
  • RECURRING

Introduction

Nequi is like a digital bank account where the user can, among other things: Keep money. Make transfers and send money without costs to any part of Colombia. Receive money even from overseas.

Refunds are available for same-day transactions only.

Supported Countries

  • Columbia

Supported Currencies

  • COP

Payment (Deposit) Flow

If you wish to perform a payout transaction in the future, you will need to use the same userTokenId and userPaymentOptionId values that are generated in this payment transaction.

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

  • userTokenId
  • amount
  • currency
  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_NEQUI_CO“
    • nequi_phone_number – must consist of 10 numbers
    • nequi_method– “qr” or “notification“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email
  • userDetails class containing: firstName, lastName, country, email
Example /payment Request
{
  "sessionToken": "<sessionToken from getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "100",
  "currency": "COP",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_NEQUI_CO",
      "nequi_phone_number": "3400100012",
      "nequi_method": "notification"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "CO",
    "email": "[email protected]"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "CO",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response
{
  "internalRequestId": 41384771,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "4972436454212160565",
  "merchantSiteId": "209631",
  "version": "1.0",
  "clientRequestId": "20240605172514",
  "sessionToken": "112b68c3-7baa-4831-8598-37f6bc72a934",
  "orderId": "43172161",
  "userTokenId": "siltoken11nequi99917",
  "paymentOption": {
    "userPaymentOptionId": "2153235881",
    "card": {}
  },
  "transactionStatus": "PENDING",
  "transactionId": "2610000000000032244"
}

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

Example /payment DMN with Status=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=38450821&userid=Lorem&merchant_unique_id=merchuniqueid&customData=56_Sm96a3ZZWG56RERLJKHkljnJKHjbxiuyTWd4WDVncS9YQURxYWZuS1VCWT0%3D&productId=moneycash&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=COP&customField1=enracha.es&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Colombia&state=&city=Madrid&zip=123456&phone1=3400100014&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=3400100014&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=1.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_NEQUI_CO&ID=&merchant_id=5416795427517477813&responseTimeStamp=2022-12-07.07%3A40%3A19&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=13395012nequicoredir&user_token=auto&userPaymentOptionId=8389551&TransactionID=2110000000007968287&externalTransactionId=NQU-183&APMReferenceID=BC393B3FA61F42F8AEEE122DDF487A9F&orderTransactionId=19221731&totalAmount=7.00&dynamicDescriptor=hristo+descriptor&item_name_1=money&item_number_1=&item_amount_1=5.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&item_name_2=cash&item_number_2=&item_amount_2=3.00&item_quantity_2=1&item_discount_2=0.00&item_handling_2=0.00&item_shipping_2=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221207&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=nullnull&sessionId=b843dab8ae9ed24895c2cf71eb5d&responsechecksum=9d0e1636fc5c936940a73f03b353455686a91014d662db659304b5f229421ca7&advanceResponseChecksum=acb54e26b3f664f43238235ce2340248e39f4d73a989f107c8d8c9febdf07ae1',
Example /payment DMN with Status=PENDING
...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=38450821&userid=Lorem&merchant_unique_id=merchuniqueid&customData=56_Sm96a3ZZWG56RERLJKHkljnJKHjbxiuyTWd4WDVncS9YQURxYWZuS1VCWT0%3D&productId=moneycash&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=COP&customField1=enracha.es&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Colombia&state=&city=Madrid&zip=123456&phone1=3400100014&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=3400100014&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=1.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_NEQUI_CO&ID=&merchant_id=5416795427517477813&responseTimeStamp=2022-12-07.07%3A38%3A18&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=13395012nequicoredir&user_token=auto&userPaymentOptionId=8389551&TransactionID=2110000000007968287&externalTransactionId=NQU-183&APMReferenceID=BC393B3FA61F42F8AEEE122DDF487A9F&orderTransactionId=19221731&totalAmount=7.00&dynamicDescriptor=hristo+descriptor&item_name_1=money&item_number_1=&item_amount_1=5.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&item_name_2=cash&item_number_2=&item_amount_2=3.00&item_quantity_2=1&item_discount_2=0.00&item_handling_2=0.00&item_shipping_2=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221207&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=nullnull&sessionId=b843dab8ae9ed24895c2cf71eb5d&responsechecksum=ec80291af869bddf577b17b1e1658f04b1dafcb7a5e86a95850fde0ccbcbc3e1&advanceResponseChecksum=28ef18147ffbebffe7d4b7c1865714d6069ac72e1883e23264443486dd6e3e4a',
Example /payment DMN with Status=DECLINE
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=9&errApmCode=9&errApmDescription=Rejected+by+carrier.&errScCode=9999&errScDescription=Default&Reason=Default&ReasonCode=9999&PPP_TransactionID=38473981&userid=Lorem&merchant_unique_id=merchuniqueid&customData=56_Sm96a3ZZWG56RERLJKHkljnJKHjbxiuyTWd4WDVncS9YQURxYWZuS1VCWT0%3D&productId=moneycash&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=COP&customField1=enracha.es&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Colombia&state=&city=Madrid&zip=123456&phone1=0987654321&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=0987654321&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=1.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_NEQUI_CO&ID=&merchant_id=5416795427517477813&responseTimeStamp=2022-12-14.09%3A20%3A16&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=13395012nequineg2&user_token=auto&userPaymentOptionId=8394211&TransactionID=2110000000008028882&externalTransactionId=NQU-235&APMReferenceID=D1137C56B6B0062C5EABCF7D9F6C5696&orderTransactionId=19233111&totalAmount=7.00&dynamicDescriptor=hristo+descriptor&item_name_1=money&item_number_1=&item_amount_1=5.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&item_name_2=cash&item_number_2=&item_amount_2=3.00&item_quantity_2=1&item_discount_2=0.00&item_handling_2=0.00&item_shipping_2=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221214&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=nullnull&sessionId=fd2826fa6d34c893adcf9373c384&responsechecksum=6337364fcb7f907d5502a0602585a0b539bee7cc87b313c592d55b9f969572f8&advanceResponseChecksum=fd3fd3e79cf1215174f00518a799ba345cce14c5416f7aaf99cd462c0b7e05b6',

Payout (Withdrawal) Flow

Follow these steps to perform a payout:

When relevant, it is preferable that a merchant uses the userTokenId generated from a payment transaction that was previously performed. If so, the merchant should skip to Step 2.

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": "CO",
  "firstName": "John",
  "lastName": "Smith",
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /createUser Response
{
  "internalRequestId": 34147331,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "4972436454212160565",
  "merchantSiteId": "209631",
  "version": "1.0",
  "clientRequestId": "20231006102743",
  "userId": 139902701
}

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

If the user has an existing UPO (which contains the user’s previously stored APM account details), then the merchant should skip to Step 3.

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

  • userTokenId – The unique user identifier in your system.
  • paymentMethodName: “apmgw_NEQUI_CO“
  • apmData class containing:
    • nequi_phone_number – must consist of 10 numbers
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_NEQUI_CO",
  "apmData": {
    "nequi_phone_number": "3400100012"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

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

Example /addUPOAPM Response
{
  "internalRequestId": 34147351,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "4972436454212160565",
  "merchantSiteId": "209631",
  "version": "1.0",
  "clientRequestId": "20231006102813",
  "userPaymentOptionId": 2153042111
}
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, the user receives a DMN (sent to the notificationUrl parameter you can provide in the request) that includes the result of the transaction.

Example /payout DMN with wdRequestStatus=Approved
...'wdOrderId=5412191&wdRequestId=6793081&gwTrxId=2610000000000033017&notificationType=WITHDRAW_ORDER_NOTIFICATION&merchantSiteId=209631&merchantGwId=4972436454212160565&merchantLocale=en_US&wdRequestState=Closed&wdRequestStatus=Approved&wdOrderStatus=Settled&settlementType=WITHDRAWAL&gwErrCode=0&gwExtendedErrorCode=0&apmTrxId=2610000000050153&apmReferenceId=1EF37104BDA0FAB42355781EA3604554&apmErrorCode=0&firstName=John&lastName=Doe&userTokenId=siltokenrfrfth77rr&zip=M6T+1J1&city=Ontario&country=CO&phone1=%2B14161238888&email=ivanp%40abv.bg&address=Test+Address&amount=50.00&approvedAmount=50.00&currency=COP&userId=UID&userPMId=2153236391&paymentMethod=apmgw_NEQUI_CO&version=1.0&pmDisplayName=3400100014&customField1=meccabingo.com&customField3=333&client_ip=127.0.0.1&wdOrderAmount=50.00&wdOrderCurrency=COP&responseTimeStamp=2024-06-07.13%3A35%3A50&ExternalaccountID=3400100014&feeAmount=0.0&transactionAmount=50.0&merchantUniqueId=merchant_unique_id&upoRegistrationDate=20240607&checksum=b6a8729a1bc333ce59be019e956d8ddd',
Example /payout DMN with wdRequestStatus=Declined
...'wdOrderId=5412211&wdRequestId=6793101&gwTrxId=2610000000000033020&notificationType=WITHDRAW_ORDER_NOTIFICATION&merchantSiteId=209631&merchantGwId=4972436454212160565&merchantLocale=en_US&wdRequestState=Closed&wdRequestStatus=Declined&wdOrderStatus=Error&settlementType=WITHDRAWAL&gwErrCode=0&gwReason=GENERIC_ERROR-SC_MISSING_MANDATORY_FIELD&gwExtendedErrorCode=0&apmTrxId=2610000000050156&apmReferenceId=BB429A0019E4F8CE0DD2F4DAAE228787&apmErrorCode=0&firstName=John&lastName=Doe&userTokenId=siltokenrfrfth77rr&zip=M6T+1J1&city=Ontario&country=CO&phone1=%2B14161238888&email=ivanp%40abv.bg&address=Test+Address&amount=50.00&approvedAmount=0.00&currency=COP&userId=UID&userPMId=2153236391&paymentMethod=apmgw_NEQUI_CO&version=1.0&pmDisplayName=3400100014&customField1=meccabingo.com&customField3=333&client_ip=127.0.0.1&wdOrderAmount=50.00&wdOrderCurrency=COP&responseTimeStamp=2024-06-07.13%3A50%3A12&ExternalaccountID=3400100014&feeAmount=0.0&transactionAmount=50.0&merchantUniqueId=merchant_unique_id&upoRegistrationDate=20240607&checksum=828d870c3f5adf78c90fce9cd82a1a4d',

User Experience

QR Code

  1. The user is redirected to a page on which a QR code appears.
    The user can either scan the QR using the Nequi mobile app or take a screenshot of the QR code and upload it to the app.

Notification

The user receives a push notification in the Nequi mobile app.

Testing

Test credentials and testing scenarios can be provided by Nuvei if necessary. You can contact Nuvei support for assistance.

Last update iconLast modified October 2024