Skip to main content

​
Overview

SoyFri is a digital wallet payment method available in Guatemala, allowing customers to pay directly from their SoyFri account using their registered phone number.

Supported Country

Guatemala (GTM)

Processing Time

Instant confirmation

Wallet-Based

No card or bank needed

​
How It Works

1

Create Payment

Your backend calls POST /api/transactions/charges with the customer’s phone number.
2

Receive Checkout URL

You get a urlCheckout to redirect the customer.
3

Customer Confirms

Customer approves the payment in their SoyFri account.
4

Webhook Notification

Your server receives a webhook with the final status.

​
Create SoyFri Payment

​
Request

curl -X POST "https://api-sandbox.88pay.io/api/transactions/charges" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-session-id: YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "PAYIN",
    "method_code": "SOYFRI",
    "method_category": "WALLET",
    "amount": 10.00,
    "currency": "GTQ",
    "country": "GTM",
    "description": "Order #12345",
    "customer_id": "cust_9876510",
    "notification_url": "https://yoursite.com/webhook",
    "return_url": "https://yoursite.com/success",
    "customer": {
      "customer_account_identifier_value_type": "phone",
      "customer_account_identifier_value": "50001464"
    }
  }'

​
Response

{
  "status": "Success",
  "code": 200,
  "data": {
    "urlCheckout": "https://link.88pay.io/ABC123",
    "reference": "IP9BD7CJES6",
    "amount": 10.00,
    "currency": "GTQ"
  }
}

​
Fields

​
Base Fields

FieldTypeRequiredNotes
flowstringYesAlways "PAYIN"
method_codestringYesAlways "SOYFRI"
method_categorystringYesAlways "WALLET"
amountnumberYesAmount to charge
currencystringYesAlways "GTQ"
countrystringYesAlways "GTM"
descriptionstringYesOrder or product description
customer_idstringYesYour internal customer identifier
notification_urlstringYesWebhook URL for status updates
return_urlstringNoURL to redirect customer after payment

​
Customer Object

FieldTypeRequiredNotes
customer_account_identifier_value_typestringYesAlways "phone"
customer_account_identifier_valuestringYesCustomer’s SoyFri registered phone number

​
Customer Experience

1

Redirect to Checkout

Customer is redirected to urlCheckout — a secure 88Pay hosted page.
2

Confirm with SoyFri

Customer approves the payment using their SoyFri wallet account.
3

Payment Processed

Transaction is confirmed instantly.
4

Return to Site

Customer is redirected to your return_url.
Important: Don’t rely on return_url for order fulfillment. Always use webhooks — customers may close the browser before the redirect.

​
Webhook Notifications

    {
      "transaction_status": "COMPLETED",
      "transaction_reference": "IP9BD7CJES6",
      "transaction_amount": "10.00",
      "transaction_payment_method": "SOYFRI"
    }
Action: Fulfill order, send confirmation email.
Webhook implementation guide →

​
Common Issues

Problem: urlCheckout not received or redirect failsSolutions:
    if (!data.urlCheckout) {
      console.error('No checkout URL in response');
      return;
    }

    window.location.href = data.urlCheckout; // ✅ Correct
Common reasons:
  1. Phone number not registered in SoyFri
  2. Insufficient wallet balance
  3. Customer cancelled the payment
  4. Session expired before confirmation
Customer actions:
  • Verify the phone number is correct
  • Check SoyFri wallet balance
  • Try again
Solutions:
  • Verify your notification_url is publicly accessible and returns 200 OK
  • Check webhook logs in your dashboard
  • Query transaction status via API using the reference
  • Contact support with the transaction reference

​
Best Practices

Always Use Webhooks

Never rely solely on return_url for order fulfillment

Validate Phone Number

Ensure the phone number is registered in SoyFri before submitting

Store Reference

Save reference for tracking and support

Test Thoroughly

Test approved, rejected, and pending scenarios in sandbox

​
Next Steps

Webhooks

Implement payment notifications

Error Handling

Handle declined payments gracefully

Countries & Methods

See all supported countries and methods

API Reference

Full technical documentation