Skip to main content

Salesforce integration

Edge Pay treats your Salesforce org as the system of record. Amounts come from the org, eligibility is checked against the org, and every successful payment is written back to the org. This page describes the org-side pieces and who is responsible for each.

The REST endpoint​

The platform calls a single Apex REST endpoint in your org for payment operations. It is declared in payment.yaml:

salesforce:
  mode: live
  kaptio_namespace: KaptioTravel
  rest_endpoint: /services/apexrest/edge/payments

This endpoint handles the org side of the payment lifecycle: reading itinerary and schedule data for the session, and receiving the writeback when a payment completes. It is part of the Kaptio-managed Salesforce package configuration and is set up during onboarding.

The payment gateway record​

Inside the org, payment routing is configured on a PaymentGateway__c record. Its PropertiesJSON__c field carries the two values that connect the org to your Edge Pay tenant:

{
  "base_url": "https://pay.example.com",
  "tenant_id": "meridian"
}
  • base_url — the payment page host for your tenant, provided by Kaptio.
  • tenant_id — your tenant identifier, matching tenant_id in payment.yaml.

When a payment link is generated from the org (from a document action or by an agent), this record tells the org where to send the payer and which tenant configuration governs the session.

Payment schedules drive amounts​

Edge Pay never hardcodes deposit or balance amounts. The payment_model block in payment.yaml sets deposit.from_salesforce: true, which means:

  • Payment schedule rows on the itinerary (PaymentSchedule__c records) define the deposit, installment, and final-balance amounts and due dates.
  • The payment page presents whatever the schedule defines — one row or many — rather than a fixed deposit/full binary.
  • In the call-center scenario, agents select which schedule rows to pay now and can optionally schedule the remainder.

If amounts look wrong on a payment page, the schedule rows on the itinerary are the first place to check.

Payment writeback​

When a payment succeeds, the platform writes the result back through the REST endpoint:

  • The payment is recorded against the itinerary, with the payer details collected on the page.
  • Payment schedules are updated to reflect what was paid.
  • If configured, post-payment documents (such as a financial summary) are generated against the updated booking — see payment.yaml reference.

The tokenize scenario is the one exception: it vaults a card without charging and deliberately skips writeback until the booking is confirmed.

Eligibility queries​

The payment_eligibility rules in payment.yaml are SOQL queries executed against your org in real time, before the payment form renders. The baseline's enabled rule gates on booking status:

    - id: itinerary_status_check
      query: >-
        SELECT KaptioTravel__Status__c FROM KaptioTravel__Itinerary__c WHERE Id
        = :itineraryId AND KaptioTravel__Status__c NOT IN ('Option', 'Booked')
      block_if: results_exist

Two implications for your Salesforce administrator:

  • Status values must match the org. The rule above assumes Option and Booked are the payable statuses. If your org uses different status values, the rule must be updated to match.
  • Stub rules need org-specific IDs. The disabled stubs (on_request_confirmed, final_payment_due) carry placeholder tokens such as :onRequestStatusId that must be replaced with your org's actual record IDs and field values before enabling. Each stub's required_setup note states exactly what is needed.

Extra itinerary fields​

The payment page can display org fields in its price summary — but only fields declared in itinerary_extra_select_fields:

salesforce:
  itinerary_extra_select_fields:
    - KaptioTravel__Subtotal__c
    - KaptioTravel__TotalAmountNet__c
    - Insurance__c
    - Total_Discount__c

This list is the query contract between the platform and your org. Adding a summary_breakdown line that reads a new field is always a two-part change: declare the field here, then reference it in the breakdown. Custom fields (such as Insurance__c above) work as long as they exist on the itinerary object and are readable by the integration user.

Who sets up what​

ResponsibilityOwner
Gateway credentials in the secret vault (vault::braintree_*)Kaptio — provisioned at onboarding; never handled by the customer in plain text
Tenant secret for signed payment sessionsKaptio — provisioned at onboarding
Payment page hosting and Kaptio Pay service routingKaptio — endpoints are managed per environment
PaymentGateway__c record (base_url, tenant_id)Customer Salesforce admin — created in the org during onboarding
Itinerary status values used in eligibility rulesCustomer Salesforce admin — confirms or supplies the org's values
Org-specific record IDs for stub eligibility rulesCustomer Salesforce admin — supplied before a stub is enabled
Payment schedule setup (types, due dates, amounts)Customer Salesforce admin — standard Kaptio schedule configuration
payment.yaml itselfShared — Kaptio forks the baseline; changes flow through the configuration repository's review process

When referencing your org in configuration or support requests, use the placeholder form 00Dxx0000000000XXX for org IDs in anything written down outside the org itself.