Smilepayz

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

Open Smilepayz in the provider directory and press Connect at Smilepayz Provider Overview page in the New connection section. Choose Provider account.

Step 2 - Fill in fields and select settings

• Merchant ID -> merchant_id
• Secret -> secret
• Merchant Private Key -> private_key
• Test Mode -> (enable if you are using sandbox credentials)
• API URL -> api_url (optional, overrides the default Smilepayz sandbox/production host; leave empty unless your Smilepayz manager gave you a different host)

Choose Currency and Features. You can set these parameters according to available currencies and features for your Smilepayz account, but it is necessary to check details of the connection with your Corefy account manager.

First request to Corefy API (MIN)

What it does: creates a payment-invoice. The customer is redirected to the Smilepayz hosted payment page and chooses the bank there.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "bank_transfer_aggregated_pen_hpp",
      "currency": "PEN",
      "amount": 100
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "bank_transfer_aggregated_pen_hpp",
      "currency": "PEN",
      "amount": 100,
      "description": "Order 12345",
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "email": "johndoe@example.com",
        "phone": "51900000000"
      },
      "service_fields": {
        "document_type": "NID",
        "document_id": "12345678"
      }
    }
  }
}

• description is shown to the payer; it is cut to 64 characters. If it is not sent, the payment ID is used.
• service_fields.document_type must be one of the Smilepayz values: NID (National ID), FID (Foreigner ID), PP (Passport), TIN (Tax Identification Number). It is sent as is, so use exactly these codes.
• service_fields.document_id is the document number matching document_type.

Extended request (MAX)

Why add extra fields (typical reasons):

• Provide additional customer details for compliance/reconciliation
• Positively influence conversion rate
• Include optional fields required by your specific flow

Options

Options are configured on the Corefy side and affect how Corefy builds provider requests or processes responses.

Currently available options (1)

• finalize_after_hours - after how many hours an expired payment is closed as failed

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

Open Smilepayz in the provider directory and press Connect at Smilepayz Provider Overview page in the New connection section. Choose Provider account.

Step 2 - Fill in fields (provider -> Corefy)

• Merchant ID -> merchant_id
• Secret -> secret
• Merchant Private Key -> private_key
• Test Mode -> (enable if you are using sandbox credentials)
• API URL -> api_url (optional, overrides the default Smilepayz sandbox/production host)

First request to Corefy API

What it does: creates a payout-invoice (bank transfer in PEN to a bank account in Peru).

Actual

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "service": "bank_transfer_pen",
      "currency": "PEN",
      "amount": 100,
      "fields": {
        "bank_account": "19100000000000",
        "account_type": "CHECKING",
        "cci_key": "00219100000000000000",
        "beneficiary_full_name": "John Doe",
        "beneficiary_email": "johndoe@example.com",
        "beneficiary_phone": "51900000000",
        "document_type": "NID",
        "document_id": "12345678"
      }
    }
  }
}

All eight fields are required by Smilepayz. If one of them is missing, Smilepayz declines the payout.

• bank_account - beneficiary bank account number, up to 32 characters
• account_type - CHECKING (current/checking account) or SAVINGS (savings account)
• cci_key - CCI, the 20-digit Peruvian interbank account code
• beneficiary_full_name, beneficiary_email, beneficiary_phone - beneficiary details (phone in local format)
• document_type - NID (National ID), FID (Foreigner ID), PP (Passport) or TIN (Tax Identification Number)
• document_id - document number matching document_type

account_type and document_type are sent as is, so use exactly these codes. The optional description is cut to 64 characters; if it is not sent, the payout ID is used.