Skip to content

Logo

Pi Pay

Experience the World of Infinite Possibilities.

Supports in this guide: Payments

Provider website: pipay.com

What you need to do for start processing transactions (brief summary)

  1. Get your credentials (from Pi Pay)
  2. Connect in Dashboard
  3. Send an API request

Prerequisites: get from Pi Pay

To get connected, send a request at pipay.com/contact-us or contact your Pi Pay manager directly, and submit the required documents to verify your account.

Get the following values for your Pi Pay account:

  • Username -> Corefy field username -> identifies your Pi Pay merchant account; used together with Password to obtain an auth token.
  • Password -> Corefy field password -> used together with Username to obtain an auth token.
  • Vendure token -> Corefy field vendure_token -> sent as a separate header on every authenticated request to Pi Pay.
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

Open Pi Pay in the provider directory and press Connect at Pi Pay Provider Overview page in the New connection section. Choose H2H Merchant account.

Step 2 - Fill in fields and select settings

  • Username
  • Password
  • Vendure token
  • Currency / Features -> choose values available for your Pi Pay account

Success

You have connected Pi Pay H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and processes a direct card (H2H) payment.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "8413694f-da4e-4223-b00b-09acc5094ce5",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "gateway_options": {
        "cardgate": {
          "tokenize": ""
        }
      },
      "customer": {
        "reference_id": "cus_123"
      }
    }
  }
}

Important

customer.name is used as the cardholder name on the card data Pi Pay receives. There is no fallback placeholder - if it's omitted, Pi Pay simply gets no cardholder name rather than a substituted fake one.

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "b6cfd163-6f43-4a3a-84e1-72593ac9273f",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 15.5,
      "gateway_options": {
        "cardgate": {
          "tokenize": ""
        }
      },
      "customer": {
        "reference_id": "cus_123",
        "name": "Serge Kot"
      }
    }
  }
}

Extended request (MAX)

Why add extra fields (typical reasons): - Provide the cardholder's name, used on the card data sent to Pi Pay - Include optional fields required by your specific flow

Constants (fallback fields)

Constants are static values Corefy sends to Pi Pay when creating the underlying order (its line items), instead of dynamic data from your API request, when those fields are missing in the request.

Priority (predictable rule): 1. If a value is present in the request -> Corefy uses the request value 2. Else if the constant is set -> Corefy uses the constant 3. Else -> provider may reject the request or apply its defaults (depends on provider)

Currently available constants (constant -> Corefy API field)

  • STOCK_KEEPING_UNIT -> the order's line-item SKU sent to Pi Pay
  • QUANTITY -> the order's line-item quantity sent to Pi Pay

Refunds

Pi Pay does not support refunds - the payment gateway has no refund capability wired up for this connector.

Additional info

  1. Callback + active reconciliation - every sale sends Pi Pay a webhook URL; on receiving that callback, Corefy also actively re-checks the transaction status with Pi Pay (via the same lookup used for manual reconciliation) before finalizing it.
  2. No recurring - this connector does not support saving or charging a card token through Corefy; every sale requires full card data.
  3. CVV is required - Pi Pay does not support non-CVV (stored-card) sales.
  4. Auth token handling - Corefy logs in with your Username/Password to obtain a bearer token, caches it, and automatically refreshes it when it expires or Pi Pay rejects a request as unauthorized/forbidden. The Vendure token is sent as a separate header on every authenticated request, independent of that bearer token.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify Username, Password and Vendure token
  • Currency or service is not supported -> confirm allowed currencies/features in your Pi Pay account and in Corefy
  • Payment stuck / status not updating -> Corefy confirms status via callback and active reconciliation; contact support with the original Pi Pay order ID if it still doesn't resolve
  • Refund requested -> not available for this connector; settle refunds directly with Pi Pay outside of Corefy

Question

Still looking for help connecting your Pi Pay account? Please contact our support team!