Build a connector
Add a payment gateway, a courier or a messaging provider with the connector SDK.
A connector teaches the platform one provider. It turns the provider's requests, answers, error codes and webhooks into the platform's own types, so routing, retries, refunds and reconciliation work the same on every gateway. Partners build connectors for gateways, couriers and WhatsApp or SMS providers with the connector SDK in pkg/connsdk of the repository. Bill pay connectors come later, with bill pay itself.
The interfaces
Import pkg/connsdk and nothing under internal/. The SDK's types are the platform's own, so the platform's registries take your connector as it is.
- Payment gateways implement
connsdk.Connector:Create,Status,Refund,ParseWebhookandHealth. Optional interfaces cover what only some gateways do:Account(sellers connect their own credentials),RefPeeker,HostedForm,Tokeniser(saved cards),Mandator(UPI AutoPay and card mandates),Holder(pre-authorisation),VPAVerifierandCataloguer. - Couriers implement
connsdk.Courier, and optionallyCourierAccount,NDRActorandAWBPeeker. - Messaging providers implement
connsdk.MessagingProvider.
The rules are in the package documentation. The short version:
- Idempotent on the platform's ids: a repeated
Create,RefundorBookreturns the first result. It never opens a second payment or shipment. - Every refusal carries a reason from the canonical decline dictionary, and every failed payment carries the provider's own code.
- Every error wraps one of the SDK's sentinels. A timeout or 5xx is
ErrProviderUnavailable, so the router tries the next gateway, and a provider's refusal isErrRejected. ParseWebhookchecks the signature before it reads anything, and never calls the network.- Credentials and customer data are never logged. A card number never reaches a connector.
Start from the example
pkg/connsdk/example/examplepg is a complete payment connector for a made-up gateway. It has three files: the connector, an in-process fake of the gateway, and the contract test. Copy it, rename it, and replace the fake with one that matches your provider's sandbox: the same paths, bodies, signature scheme and codes. The contract then runs the same way against the fake in seconds and against the real sandbox when you have credentials. The example also has a test that fails if any file imports a platform internal package. Keep it.
The contract kit
Package pkg/connsdk/kit runs the contract. Call kit.RunPayment, kit.RunCourier or kit.RunMessaging from a test in your package, with a harness that knows how to make each outcome happen on your sandbox. For payments that means a success, insufficient funds, the issuer down, a timeout and a payment left pending. Each clause is a subtest, so a failure names the rule that was broken: create_is_idempotent, refund, webhook and so on.
Some clauses are optional. A gateway that sends no webhooks skips the webhook clause, and the platform polls it instead. A courier whose sandbox cannot refuse a booking skips that clause. A messaging provider whose receipts come another way skips the receipts clause. An optional clause that runs must still pass.
Certification
The certification run (pkg/connsdk/certify, or cli connectors certify <dir> on the platform) runs every test in your package and writes a report. The report records the kit version, the Go version, every clause and whether it passed, and a SHA-256 of your source. It passes only when:
- at least one kit ran;
- every required clause passed and none was skipped;
- no other test failed and the package built.
Optional clauses that did not run are listed, so the reviewer sees what was not exercised.
A connector is certified for one kit version. Any change to a kit clause bumps the version, and connectors certified on an older version must certify again. The source hash ties the report to the code: the platform checks it again before it takes a release, so a change after certification needs a new run.
Review and listing
A passing report is necessary, but it is not enough. An engineer reviews every connector before it is merged. They read the mapping against the provider's documentation, check that nothing logs a secret, and run the contract against the provider's real sandbox. A connector that passes against its own fake has shown its shape, not that it matches the real API. Only after that review is a connector listed in the marketplace as certified. Each later release is certified and reviewed the same way.
The connector-building agent
The platform's engineers can start a connector with an agent. Given a provider's API documentation, it writes the three files in a workspace of its own on the SDK and the example. It runs the contract in a container with no network, fixes what fails, and lists everything it was unsure of. It never writes to the repository and never merges. Its output is a draft for the same review as any partner's connector, with the report, the full transcript and a review checklist beside it.