Consumer integration runbook

Use this checklist when a backend service starts using APICenter. The Management guides explain access and registry setup; the SDK guide covers installation and API methods.

Before integration

• Confirm the service is registered under the correct organization, tribe, and project.
• Ask an operator to issue separate test and live service credentials and grant only the scopes the service needs.
• Store APICENTER_SERVICE_SECRET and any payment credential in the backend secret manager. Never send them to a browser or commit them.
• Add the package's GitHub Packages configuration and a CI token with package read access.
• If payment lifecycle events are part of the integration, ask the APICenter operator to configure the consumer's Pub/Sub push subscription and Cloud Run OIDC identity.
• Make event processing idempotent by eventId and monotonic by aggregateVersion.

Create a payment checkout

Create a stable idempotency key for the business operation and persist it with the order before calling APICenter. Reuse it after timeouts or transient failures.

const checkout = await api.payments.checkouts.create(
  {
    referenceId: order.id,
    amount: { amountMinor: order.totalMinor, currency: 'PHP' },
    successUrl: 'https://orders.example/payments/success',
    cancelUrl: 'https://orders.example/payments/cancel',
  },
  { idempotencyKey: order.checkoutRequestKey },
);

Treat the checkout as pending until your service processes the payment.checkout.paid event. A browser redirect alone does not prove payment. Payment resource IDs are opaque APICenter IDs; do not depend on provider-specific fields.

Process payment events

Verify the Cloud Run OIDC token on the push endpoint. Validate the event envelope, ignore an eventId already recorded, and apply only an event whose aggregateVersion is newer than the version stored for that resource. Acknowledge a valid duplicate after confirming it was already applied. See payment event delivery for the envelope and delivery behavior.

Handle failures and rollbacks

Retry a transient API failure with the same idempotency key and body. Do not issue a new key just because the first response timed out; the original operation may have completed.

For an event delivery failure, ask the APICenter operator to inspect the subscription and dead-letter flow. After correcting the consumer, replay the event and retain its original eventId and aggregate version. If a payment cutover rollback is announced, continue serving the consumer's existing local state and pause new payment commands until the operator confirms the path forward. Do not call PayMongo directly.

When escalating, include the environment, APICenter resource reference, event ID, and correlation ID. Never include service secrets, payment keys, or provider credentials. Operator procedures remain in the internal docs/ collection.