Skip to content

Logo

CitrinePay (Citrine Merchant Services)

Supports in this guide: Payments | Payouts

Provider website: citrinepay.co

Note

The provider's registered entity name is "Citrine Merchant Services"; the connection and its public-facing brand are "CitrinePay", which is also this doc's citrinepay slug.

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

  1. Choose account type
  2. Get your credentials (from CitrinePay)
  3. Connect in Dashboard
  4. Send an API request

Choose account type

CitrinePay can be connected in different ways (depending on your needs):

  • If you do payouts -> choose Provider account
  • If you do payments -> choose H2H Merchant account

If you are not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from CitrinePay

To create an account, send a connection request via the CitrinePay contact page or contact your CitrinePay manager directly. Submit the required documents to verify your account and gain access.

Get the following values for your CitrinePay account:

  • Merchant ID -> Corefy field merchant_id -> where to find: CitrinePay back office / issued by CitrinePay manager
  • Partner Control -> Corefy field partner_control -> where to find: CitrinePay back office / issued by CitrinePay manager
  • Currency -> Corefy field currency -> one of: IDR, PHP, VND
  • Method -> Corefy field method -> see the allowed values per account type below
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Merchant ID -> merchant_id
  • Partner Control -> partner_control
  • Currency -> currency -> one of: IDR, PHP, VND
  • Method -> method -> one of: bank_transfer_aggregated, qr_payment_aggregated

Success

You have connected CitrinePay H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "2ede44c0-419f-4c61-b400-8ab755bad9b2",
      "service": "qr_payment_aggregated_php_hpp",
      "currency": "PHP",
      "amount": 100,
      "customer": {
        "reference_id": "e13179f8-664e-4b54-bef9-41ba9baec8e1"
      }
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "2ede44c0-419f-4c61-b400-8ab755bad9b2",
      "service": "qr_payment_aggregated_php_hpp",
      "currency": "PHP",
      "amount": 100,
      "customer": {
        "reference_id": "e13179f8-664e-4b54-bef9-41ba9baec8e1",
        "name": "John Doe",
        "email": "johndoe@email.com",
        "phone": "+639171234567",
        "address": {
          "full_address": "123 Rizal Street",
          "country": "PH",
          "city": "Manila",
          "post_code": "1000"
        },
        "metadata": {
          "ip": "1.1.1.1"
        }
      }
    }
  }
}

CitrinePay also routes bank_transfer_aggregated_php_hpp / bank_transfer_aggregated_idr_hpp (bank transfer) and qr_payment_aggregated_idr_hpp / qr_payment_aggregated_vnd_hpp (QR payment) depending on the connected Method and Currency.

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

Constants (fallback fields)

Constants are static values that Corefy can send to the provider instead of dynamic data from your API request, when those fields are missing in the request.

If a field is missing in the API request and no constant is configured for it, Corefy sends the field as empty rather than substituting any placeholder value of its own - CitrinePay does not fall back to a hardcoded email/phone/address.

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 -> the field is sent empty; CitrinePay may reject the request or apply its own defaults

Currently available constants (constant -> Corefy API field)

  • EMAIL -> customer.email
  • PHONE -> customer.phone
  • FIRST_NAME -> customer.name (first part)
  • LAST_NAME -> customer.name (last part)
  • COUNTRY_CODE -> customer.address.country
  • CITY -> customer.address.city
  • ADDRESS -> customer.address.full_address
  • POST_CODE -> customer.address.post_code
  • USER_IP -> customer.metadata.ip
Payouts processing (connect Provider account, create payout-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

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

  • Merchant ID -> merchant_id
  • Partner Control -> partner_control
  • Currency -> currency -> one of: IDR, PHP, VND
  • Method -> method -> one of: bank_transfer_php, bank_transfer_vnd, bank_transfer_idr

Success

You have connected CitrinePay Provider account!

First request to Corefy API (MIN)

What it does: creates a payout-invoice.

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "8dd30395-643d-4f3b-9a8d-9d0c14197a70",
      "service": "bank_transfer_php",
      "currency": "PHP",
      "amount": 100,
      "fields": {
        "account_number": "109420113109",
        "bank_code": "UB",
        "bank_address": "Uptown Place Mall, Bonifacio Global City, Taguig"
      }
    }
  }
}

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "8dd30395-643d-4f3b-9a8d-9d0c14197a70",
      "service": "bank_transfer_php",
      "currency": "PHP",
      "amount": 100,
      "customer": {
        "reference_id": "33cc9165-6ab2-4cee-8d9a-10f05cddbb5a",
        "name": "Juan Dela Cruz"
      },
      "fields": {
        "account_number": "109420113109",
        "bank_code": "UB",
        "bank_address": "Uptown Place Mall, Bonifacio Global City, Taguig"
      }
    }
  }
}

CitrinePay also routes bank_transfer_vnd and bank_transfer_idr depending on the connected Method and Currency.

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

Additional info

  1. CitrinePay does not support refunds through Corefy - the connector has no refund operation implemented. Reconciliation (status check) is supported for both Payments and Payouts.
  2. Payment and payout callbacks are delivered to Corefy automatically - no manual callback URL setup is needed on the CitrinePay side.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the Merchant ID and Partner Control for the selected account type
  • Currency or service is not supported -> confirm the allowed currency/method combination in your CitrinePay account and in Corefy
  • Missing required fields -> provide missing request fields or configure constants
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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