Introduction

A financial service provider that offers various financial services such as money transfers, bill payments, and more. It’s particularly popular in Colombia.

Supported Countries

• Colombia

Supported Currencies

• COP
• USD

Payment (Deposit) Flow

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_Efecty“
• deviceDetails
• userDetails class containing: firstName, lastName, country, email

You can also include the dynamicDescriptor class and its parameters:

• merchantName
• merchantPhone

Example /payment Request (without UPO)

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "amount": "100",
  "currency": "COP",
  "userTokenId": "<unique customer identifier in merchant system>",
  "dynamicDescriptor": {
    "merchantName": "<merchantName>",
    "merchantPhone": "<merchantPhone>"
  },
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Efecty"
    },
    "deviceDetails": {}
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "CO",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response (without UPO)

{
  "internalRequestId": 34998931,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "1102398682906145682",
  "merchantSiteId": "228311",
  "version": "1.0",
  "sessionToken": "34bf2082-eb4d-43a8-813e-92e779f14a63",
  "orderId": "41464281",
  "userTokenId": "testefectydeposit01",
  "paymentOption": {
    "redirectUrl": "https://apmtest.gate2shop.com/ppp/resources/cdn/v1/payment-details-22193.html?purchaseDate=2023-11-20T08%3A25%3A34.148Z&agreement=110342&transactionStatus=pending&buyerEmail=test%40test.com&description=test&methodName=efecty&language=EN&paymentAmount=5000.0&transactionId=PV-0000000372334&paymentNumber=90984050558",
    "userPaymentOptionId": "2153086441",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

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 /payment request.

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

{
  "merchantSiteId":"<your merchantSiteId>",
  "merchantId":"<your merchantId>",
  "userTokenId":"<unique user identifier in merchant system>",
  "clientRequestId":"<unique request ID in merchant system>",
  "firstName":"John",
  "lastName":"Smith",
  "address":"22 Main Street",
  "email":"[email protected]",
  "countryCode":"CO",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":139798011,
  "internalRequestId":25129831,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"1102398682906145682",
  "merchantSiteId":"228311",
  "version":"1.0",
  "clientRequestId":"20230228133513"
}

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_Efecty“
• apmData class containing: “efecty_personal_id“
• billingAddress class containing: country and email

Example /addUPOAPM Request

{
  "merchantSiteId":"<your merchantSiteId>",
  "merchantId":"<your merchantId>",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientRequestId":"<unique request ID in merchant system>",
  "paymentMethodName":"apmgw_Efecty",
  "apmData":{
    "personal_id":"<personal ID>"
  },
  "billingAddress":{
    "country":"CO",
    "email":"[email protected]"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /addUPOAPM Response

{
  "userPaymentOptionId":2152829771,
  "internalRequestId":25129841,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"1102398682906145682",
  "merchantSiteId":"228311",
  "version":"1.0",
  "clientRequestId":"20230228133537"
}

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.

You can also include the dynamicDescriptor class and its parameters:

• merchantName
• merchantPhone

After the transaction is processed, Nuvei sends a 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=38837311&userid=martoken999&merchant_unique_id=12345&customData=MartinakTEST&productId=&first_name=&last_name=&email=&currency=COP&clientUniqueId=12345&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=228311&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Efecty&ID=&merchant_id=1102398682906145682&responseTimeStamp=2023-03-13.09%3A11%3A47&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=martoken999&userPaymentOptionId=2152835931&TransactionID=2110000000008840269&externalTransactionId=H2H-6291&totalAmount=500.0&dynamicDescriptor=Rank+Descriptor&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230313&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=4ef548d5ca52133be336baa4385d6832&advanceResponseChecksum=b6b97ec989adbb757f27ffe58be9c101',

Example /payout DMN with status=DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=Transaction+Not+Found&errScCode=9999&errScDescription=Default&Reason=&ReasonCode=&PPP_TransactionID=38795501&userid=martoken5&merchant_unique_id=12345&customData=MartinakTEST&productId=&first_name=&last_name=&email=&currency=COP&clientUniqueId=12345&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=228311&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_Efecty&ID=&merchant_id=1102398682906145682&responseTimeStamp=2023-02-28.13%3A11%3A23&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=martoken5&userPaymentOptionId=2152829771&TransactionID=2110000000008738580&totalAmount=5000.0&dynamicDescriptor=Rank+Descriptor&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230228&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=dafa5f1a020f7a19e31d40c6b82844a1&advanceResponseChecksum=8b959157318559f41d59677da2ccb555',

User Experience

Deposit

1. The user is redirected to the third party page to see the payment instructions.
   
2. The user completes the deposit offline using the code they receives.
3. Once the user completes the deposit offline, a notification with status is sent.

Withdrawal

1. The user selects the Efecty payment method, enters personal ID, withdrawal amount, and presses Withdraw.
2. Once the withdraw request is successful, a message is displayed on the Cashier page.
3. After payout is confirm by the merchant, user receives an email with “reference” number.
   
4. The user goes to the physical location, and with the reference from the email and ID number (Cédula), they can collect cash (ID must be physically presented).
5. Upon expiration time or after the user collects their cash, a notification with status is sent.