Skip to content

Logo

PayJust

Supports in this guide: Payments

Provider website: payswix.com


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

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

Choose account type

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

  • If you do H2H card payments -> choose H2H Merchant account

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


Prerequisites: get from PayJust

Get the following values for your PayJust project/account:

  • KID -> Corefy field kid -> example: kid_8f3a21c4 -> the key identifier Corefy sends in the Authorization header of every request to PayJust -> where to find: PayJust backoffice / issued by PayJust manager
  • Secret -> Corefy field secret -> example: 4f9a0c3be1d27a65 -> the hex-encoded secret key Corefy uses to sign every request to PayJust (HMAC-SHA256) -> where to find: PayJust backoffice / issued by PayJust manager
  • API URL (optional) -> Corefy field api_url -> the PayJust API base URL; leave empty to use the default PayJust API URL -> where to find: PayJust backoffice / issued by PayJust manager

Important

Be sure to check with the manager if you require to provide a white list of IPs, and if so, specify IP addresses from the Corefy list.


Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • KID -> kid
  • Secret -> secret (hex string)
  • API URL -> api_url (optional - leave empty to use the default PayJust API URL)
  • Test Mode -> (enable if you are using sandbox credentials - in this mode every payment asks PayJust for a successful test outcome. Sandbox or production is set by the credentials, not by this toggle)

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

Success

You have connected PayJust H2H Merchant account!


First request to Corefy API (MIN)

What it does: creates a payment-invoice.

PayJust requires the customer's name, email and country for every payment. If any of them is missing, PayJust rejects the payment and it fails. If you can't send them in the request, set the matching constants (name, email, country_code) once on the connection instead (see Constants).

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "3f6c1e2a-9b7d-4c0e-8a51-2d4f7b9e6c13",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "cus_4a9d2e71",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "address": {
          "country": "DE"
        }
      }
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "b8e2d4f1-6a3c-4e9b-9c17-5f0a2e8d4b61",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "cus_7c1e9a42",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "address": {
          "country": "DE",
          "region": "Berlin",
          "city": "Berlin",
          "street": "Main street 1",
          "post_code": "10115"
        }
      }
    }
  }
}

customer.name is used only when the cardholder name from the card data is not available. customer.address.country must be a 2-letter ISO code (e.g. DE).


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.

So, if a field is missing in the API request, Corefy can take the value from the configured Constants.

After the successful connection, fill in constants for necessary routes in editing menu.

Priority (predictable rule):

  1. If a value is present in the request -> Corefy uses the request value
  2. Else if the constant is set and value isn't present in the request -> Corefy uses the constant
  3. Else -> the field isn't sent to PayJust. Name, email and country are required by PayJust, so it rejects the payment with error code 25 ("Wrong params") and the payment fails

Currently available constants (constant -> Corefy API field)

  • name -> customer.name (used only when the cardholder name is not available either)
  • email -> customer.email
  • country_code -> customer.address.country (2-letter ISO code, e.g. DE)

Refunds

Refunds aren't available for PayJust in Corefy.


Additional info

  1. 3D Secure. If PayJust requires 3D Secure, the customer is redirected to PayJust's page to complete it. After that, Corefy gets the final payment status from PayJust.

  2. Callbacks and return URLs. The webhook URL and the 3DS success/fail return URLs are set up on PayJust's side, not in the Corefy Dashboard. Ask your Corefy account manager to arrange this with PayJust before you go live.

  3. Status check. PayJust callbacks are not signed. That's why, on every callback, Corefy requests the payment status from PayJust's API and updates the payment from that answer, not from the callback body.


FAQ / Troubleshooting

  • Invalid credentials / auth error -> check that the kid and secret match the selected environment (sandbox vs production) and that secret is entered as a hex string
  • Payment failed with Wrong params: no field '…' (PayJust error code 25) -> PayJust rejected the payment because a required field wasn't sent. The message names the missing field: customer.name, customer.email or customer.countryCode. Send customer.name, customer.email and customer.address.country in the request, or set the name, email and country_code constants
  • Payment declined with an antifraud error -> PayJust's risk rules or ban list rejected the payment; contact PayJust for details
  • Payment stays pending -> make sure the webhook URL has been set up on PayJust's side (see Additional info)
  • Currency not supported -> the Corefy PayJust integration currently supports EUR only; confirm the currencies and features enabled in your PayJust account and in Corefy
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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