epayco

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 14, 2026 License: MIT Imports: 14 Imported by: 0

README

epayco

CI Go Reference

A professional, dependency-free Go SDK for the ePayco payment API.

Installation

go get github.com/movaltech/epayco

Quick start

// Sandbox vs. production is determined entirely by which key pair you pass
// here — ePayco has no separate client-side "test mode" flag.
client, err := epayco.New(os.Getenv("EPAYCO_PUBLIC_KEY"), os.Getenv("EPAYCO_PRIVATE_KEY"))
if err != nil {
	log.Fatal(err)
}

charge, err := client.Charges.Create(ctx, epayco.CreateChargeParams{
	Value: "50000", DocType: "CC", DocNumber: "1234567890",
	Name: "Juan", LastName: "Perez", Email: "juan@example.com",
	CellPhone: "3010000000", Phone: "3010000000",
	CardNumber: "4575623182290326", CardExpYear: "2029", CardExpMonth: "12",
	CardCVC: "123", Dues: "1",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(charge.RefPayco, charge.State)

See examples/charge for a complete, runnable example covering tokenization, charging, transaction lookup and webhook verification.

Two API surfaces

ePayco's own production API is not a single consistent surface, and this SDK reflects that instead of hiding it:

Client field Backend Used for
Charges, Tokens, Customers, PSE, Cash, Daviplata, Safetypay, Standard apify.epayco.co Charging, tokenizing cards, managing customers, PSE, cash, Daviplata, Safetypay, standard checkout, transaction lookup — everything ePayco documents as the current way to integrate (docs.epayco.com/docs/api).
Plans, Subscriptions api.secure.payco.co Recurring billing. ePayco's own docs (docs.epayco.com/docs/planes) don't publish a REST contract for this and point integrators to the official SDKs instead — this is that contract, ported to Go.

Both flows authenticate automatically and transparently; you never call login yourself. This split was corroborated directly against ePayco's production Postman collection and confirmed live against the sandbox API — it isn't a guess at their internal architecture, it's what their own API actually does.

Resources

client.Tokens.Create(ctx, epayco.CreateCardParams{...})           // tokenize a card
client.Customers.Create(ctx, epayco.CreateParams{...})            // create/attach a customer
client.Customers.Get(ctx, customerID)
client.Customers.List(ctx)

client.Charges.Create(ctx, epayco.CreateChargeParams{...})        // credit card
client.Charges.Get(ctx, refPayco)                                 // look up any transaction

client.PSE.Create(ctx, epayco.CreatePSEParams{...})
client.PSE.Confirm(ctx, epayco.ConfirmPSEParams{...})
client.PSE.ListBanks(ctx)

client.Cash.Create(ctx, epayco.CreateCashParams{...})              // Efecty and similar
client.Cash.ListEntities(ctx)

client.Daviplata.Create(ctx, epayco.CreateDaviplataParams{...})
client.Daviplata.Confirm(ctx, epayco.ConfirmDaviplataParams{...})  // with the OTP sent to the payer

client.Safetypay.Create(ctx, epayco.CreateSafetypayParams{...})

client.Standard.Create(ctx, epayco.CreateStandardParams{...})
client.Standard.Confirm(ctx, epayco.ConfirmStandardParams{...})

client.Plans.Create(ctx, epayco.CreatePlanParams{...})            // recurring billing
client.Subscriptions.Create(ctx, epayco.CreateSubscriptionParams{...})

Plans/Subscriptions methods return json.RawMessage instead of a typed struct: no source (official docs, the production Postman collection, or the reference SDKs) documents that API's response schema, so the SDK is honest about that instead of guessing. Decode it into your own type once you've confirmed the shape against your account.

Errors

Every operation returns (*T, error); the error is always *epayco.Error when non-nil, implementing errors.Is/errors.As:

_, err := client.Charges.Create(ctx, params)
var epErr *epayco.Error
if errors.As(err, &epErr) {
	fmt.Println(epErr.Code, epErr.Message, epErr.HTTPStatus)
}

ePayco's apify API returns HTTP 200 even for validation and business-logic failures, signaling the real outcome through a success field — the SDK already accounts for this, so a non-nil error here always means the operation genuinely failed, not just that the HTTP status was non-2xx.

Webhooks

func confirmationHandler(w http.ResponseWriter, r *http.Request) {
	payload, err := epayco.ParseWebhookPayload(r)
	if err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}

	// p_cust_id_cliente and p_key come from the ePayco dashboard
	// (Integraciones -> Llaves secretas) — NOT the same as the
	// apiKey/privateKey used to authenticate API calls.
	if !epayco.VerifySignature(pCustIDCliente, pKey, *payload) {
		http.Error(w, "invalid signature", http.StatusBadRequest)
		return
	}

	// ... update your own records using payload.RefPayco / payload.TransactionState ...
	w.WriteHeader(http.StatusOK) // ePayco expects 200 within 30s; handle idempotently, it retries on failure
}

Testing

go test ./...

runs the full unit test suite (60+ tests) against httptest fixtures captured from ePayco's production Postman collection and sandbox API — no network access required.

A separate, opt-in integration suite hits the real sandbox API and is excluded from the command above by a build tag:

EPAYCO_PUBLIC_KEY=... EPAYCO_PRIVATE_KEY=... go test -tags integration -run TestIntegration ./...

Requirements

Go 1.26.4+. No external dependencies — only the standard library.

Changelog

See CHANGELOG.md for release notes.

Contributing

Issues and pull requests are welcome. Before opening a PR, make sure go vet ./..., gofmt -l . and go test -race ./... are clean — CI enforces the same checks.

Support

This is an independent, community-maintained SDK and is not officially affiliated with ePayco. For issues with the SDK itself, please open an issue. For account or payment-processing questions, contact ePayco support directly.

License

MIT

Documentation

Overview

Package epayco is a professional, dependency-free Go SDK for the ePayco payment API (https://epayco.com). It is designed to be imported by any Go service that needs to create charges, tokenize cards, manage customers, subscriptions and plans, accept cash/PSE/Safetypay/Daviplata/standard-checkout payments, and verify confirmation webhooks.

Index

Constants

View Source
const (
	ErrCodeInvalidConfig     = 100
	ErrCodeCommunication     = 101
	ErrCodeUnknown           = 102
	ErrCodeInvalidData       = 103
	ErrCodeAuthentication    = 104
	ErrCodeNoCommunication   = 105
	ErrCodeInvalidPublicKey  = 106
	ErrCodeUnsupportedMethod = 107
	ErrCodeEncryption        = 108
	ErrCodeInvalidCashMethod = 109
)

SDK-level error codes, kept at parity with the errors.json table shared by the reference SDKs (epayco-node, epayco-php, epayco-python).

Variables

This section is empty.

Functions

func VerifySignature

func VerifySignature(pCustIDCliente, pKey string, payload WebhookPayload) bool

VerifySignature reports whether payload.Signature matches the signature ePayco computes for this transaction: sha256(pCustIDCliente^pKey^x_ref_payco^x_transaction_id^x_amount^x_currency_code).

pCustIDCliente and pKey are dashboard credentials (Integraciones -> Llaves secretas) distinct from the Client's apiKey/privateKey used to authenticate API calls — the docs never confirm they're interchangeable, so they are passed explicitly here instead of read from a *Client.

Types

type AddTokenParams

type AddTokenParams struct {
	CardToken  string `json:"cardToken"`
	CustomerID string `json:"customerId"`
}

AddTokenParams attach an existing card token to a customer.

type Bank

type Bank struct {
	Code string `json:"bankCode"`
	Name string `json:"bankName"`
}

Bank is a PSE-enabled bank, as returned by ListBanks.

func (*Bank) UnmarshalJSON

func (b *Bank) UnmarshalJSON(data []byte) error

UnmarshalJSON tolerates bankCode being a JSON string or a bare number. Confirmed live against the sandbox API: ePayco's production response mixes both within the same array (e.g. "bankCode":"1077" next to "bankCode":1022), so encoding/json's default struct decoding — which requires a consistent type — fails partway through the list.

type CardToken

type CardToken struct {
	Status  bool   `json:"status"`
	ID      string `json:"id"`
	Success bool   `json:"success"`
	Type    string `json:"type"`
	Data    struct {
		Status   string `json:"status"`
		ID       string `json:"id"`
		Created  string `json:"created"`
		Livemode bool   `json:"livemode"`
	} `json:"data"`
	Card struct {
		ExpMonth string `json:"exp_month"`
		ExpYear  string `json:"exp_year"`
		Name     string `json:"name"`
	} `json:"card"`
	Object string `json:"object"`
}

CardToken is the token generated for a credit card, returned by Create.

type CashEntity

type CashEntity struct {
	ID   string `json:"Id"`
	Name string `json:"nombre"`
}

CashEntity is a cash network available to receive payments (e.g. Efecty).

type CashService

type CashService struct {
	// contains filtered or unexported fields
}

CashService creates cash-network transactions (Efecty and similar) through ePayco's apify API.

func (*CashService) Create

func (s *CashService) Create(ctx context.Context, params CreateCashParams) (*CashTransaction, error)

Create starts a cash transaction via POST /payment/process/cash.

func (*CashService) ListEntities

func (s *CashService) ListEntities(ctx context.Context) ([]CashEntity, error)

ListEntities retrieves the cash networks available for CreateCashParams.PaymentMethod, via GET /payment/cash/entities.

type CashTransaction

type CashTransaction struct {
	RefPayco         int
	Invoice          string
	Description      string
	Value            float64
	Tax              float64
	Ico              float64
	TaxBase          float64
	Total            float64
	Currency         string
	Bank             string
	Status           string
	Response         string
	Authorization    string
	Receipt          string
	Date             string
	Franchise        string
	ResponseCode     int
	ErrorCode        string
	IP               string
	TestMode         int
	DocType          string
	Document         string
	Name             string
	LastName         string
	Email            string
	City             string
	Address          string
	Pin              string
	CodeProject      int
	PaymentDate      string
	ExpirationDate   string
	ConversionFactor float64
	Pesos            float64
}

CashTransaction is the transaction created by Create, including the pin/ reference the payer must present at the cash network's point of service. Confirmed live against ePayco's sandbox API (2026-07-02): unlike the shape documented in the production Postman collection, the real response has no "transaction" wrapper (the fields are directly under data), and uses "total"/"pesos" instead of "valorneto"/"valuePesos". Receipt is decoded leniently because ePayco encodes it inconsistently — a quoted string live, a bare number in the Postman-documented example (the same quirk as Bank.Code and TransactionDetail) — see decodeFlexString.

func (*CashTransaction) UnmarshalJSON

func (c *CashTransaction) UnmarshalJSON(data []byte) error

type ChargeService

type ChargeService struct {
	// contains filtered or unexported fields
}

ChargeService creates credit-card transactions and looks up transactions of any payment method by reference, through ePayco's apify API.

func (*ChargeService) Create

Create charges a credit card via POST /payment/process.

func (*ChargeService) Get

func (s *ChargeService) Get(ctx context.Context, referencePayco string) (*TransactionDetail, error)

Get looks up a transaction of any payment method by its ePayco reference, via POST /payment/transaction.

type ChargeSubscriptionParams

type ChargeSubscriptionParams struct {
	IDPlan    string `json:"id_plan"`
	Customer  string `json:"customer"`
	TokenCard string `json:"token_card"`
	DocType   string `json:"doc_type"`
	DocNumber string `json:"doc_number"`
	IP        string `json:"ip"`
}

ChargeSubscriptionParams are the fields accepted to charge a subscribed customer's card for the current billing period.

type ChargeTransaction

type ChargeTransaction struct {
	RefPayco        int             `json:"ref_payco"`
	Invoice         string          `json:"factura"`
	Description     string          `json:"descripcion"`
	Value           float64         `json:"valor"`
	Tax             float64         `json:"iva"`
	Ico             float64         `json:"ico"`
	TaxBase         float64         `json:"baseiva"`
	NetValue        float64         `json:"valorneto"`
	Currency        string          `json:"moneda"`
	Bank            string          `json:"banco"`
	State           string          `json:"estado"`
	Response        string          `json:"respuesta"`
	Authorization   string          `json:"autorizacion"`
	Receipt         string          `json:"recibo"`
	Date            string          `json:"fecha"`
	Franchise       string          `json:"franquicia"`
	ResponseCode    int             `json:"cod_respuesta"`
	ErrorCode       string          `json:"cod_error"`
	IP              string          `json:"ip"`
	DocType         string          `json:"tipo_doc"`
	Document        string          `json:"documento"`
	Name            string          `json:"nombres"`
	LastName        string          `json:"apellidos"`
	Email           string          `json:"email"`
	City            string          `json:"ciudad"`
	Address         string          `json:"direccion"`
	NetworkResponse NetworkResponse `json:"cc_network_response"`

	// CardTokenID and CustomerID come from a sibling "tokenCard" object in
	// the raw response (not from the transaction itself) — store the data
	// you'll need for subsequent charges (see CreateChargeParams).
	CardTokenID string `json:"-"`
	CustomerID  string `json:"-"`
}

ChargeTransaction is the transaction created by Create. Confirmed live against ePayco's sandbox API (2026-07-02): unlike the other apify payment methods (PSE, cash, Daviplata, Safetypay, standard checkout), a card charge nests the transaction under transaction.data (not transaction directly) and uses the same snake_case field names as PSE rather than camelCase.

type Client

type Client struct {

	// apify-backed services (apify.epayco.co)
	Charges   *ChargeService
	Tokens    *TokenService
	Customers *CustomerService
	PSE       *PSEService
	Cash      *CashService
	Safetypay *SafetypayService
	Daviplata *DaviplataService
	Standard  *StandardService

	// legacy core services (api.secure.payco.co) — recurring billing only,
	// see PlanService's doc comment for why.
	Plans         *PlanService
	Subscriptions *SubscriptionService
	// contains filtered or unexported fields
}

Client is the entry point to the ePayco API. Create one with New and reuse it — it is safe for concurrent use by multiple goroutines.

func New

func New(apiKey, privateKey string, opts ...Option) (*Client, error)

New creates a Client authenticated with the given ePayco public API key and private key (both available in the ePayco merchant dashboard). It does not make any network call — authentication happens lazily on the first request.

type ConfirmDaviplataParams

type ConfirmDaviplataParams struct {
	RefPayco       string `json:"refPayco"`
	IDSessionToken string `json:"idSessionToken"`
	OTP            string `json:"otp"`
}

ConfirmDaviplataParams carry the OTP the payer received on their phone.

type ConfirmPSEParams

type ConfirmPSEParams struct {
	TransactionID int64 `json:"transactionID"`
}

ConfirmPSEParams identify the PSE transaction to confirm.

type ConfirmStandardParams

type ConfirmStandardParams struct {
	Channel                  string `json:"channel"`
	Value                    string `json:"value"`
	RefEpayco                string `json:"refEpayco"`
	CurrentStatusTransaction string `json:"currentStatusTransaction"`
	StatusTransaction        string `json:"statusTransaction"`
	AuthorizationCode        string `json:"authorizationCode"`
}

ConfirmStandardParams report the outcome of a standard checkout transaction back to ePayco for confirmation.

type CreateCardParams

type CreateCardParams struct {
	CardNumber   string `json:"cardNumber"`
	CardExpYear  string `json:"cardExpYear"`
	CardExpMonth string `json:"cardExpMonth"`
	CardCVC      string `json:"cardCvc"`
}

CreateCardParams are the fields required to tokenize a credit card.

type CreateCashParams

type CreateCashParams struct {
	Invoice            string `json:"invoice,omitempty"`
	Description        string `json:"description,omitempty"`
	Value              string `json:"value"`
	Tax                string `json:"tax,omitempty"`
	TaxBase            string `json:"taxBase,omitempty"`
	Currency           string `json:"currency,omitempty"`
	TypePerson         string `json:"typePerson,omitempty"`
	DocType            string `json:"docType"`
	DocNumber          string `json:"docNumber"`
	Name               string `json:"name"`
	LastName           string `json:"lastName"`
	Email              string `json:"email"`
	CellPhone          string `json:"cellPhone"`
	EndDate            string `json:"endDate,omitempty"`
	IP                 string `json:"ip"`
	URLResponse        string `json:"urlResponse,omitempty"`
	URLConfirmation    string `json:"urlConfirmation,omitempty"`
	MethodConfirmation string `json:"methodConfirmation,omitempty"`
	PaymentMethod      string `json:"paymentMethod"`
}

CreateCashParams are the fields accepted to start a cash transaction. PaymentMethod identifies the cash network (e.g. "EF" for Efecty) and must be one of the IDs returned by ListEntities.

type CreateChargeParams

type CreateChargeParams struct {
	Value     string `json:"value"`
	DocType   string `json:"docType"`
	DocNumber string `json:"docNumber"`
	Name      string `json:"name"`
	LastName  string `json:"lastName"`
	Email     string `json:"email"`
	CellPhone string `json:"cellPhone"`
	Phone     string `json:"phone"`
	Address   string `json:"address,omitempty"`

	// First-time card data (required unless CardTokenID/CustomerID are set).
	CardNumber   string `json:"cardNumber,omitempty"`
	CardExpYear  string `json:"cardExpYear,omitempty"`
	CardExpMonth string `json:"cardExpMonth,omitempty"`
	CardCVC      string `json:"cardCvc,omitempty"`
	Dues         string `json:"dues,omitempty"`

	// Returning-customer references, in place of raw card data.
	CardTokenID string `json:"cardTokenId,omitempty"`
	CustomerID  string `json:"customerId,omitempty"`

	Tax                string `json:"tax,omitempty"`
	TaxBase            string `json:"taxBase,omitempty"`
	Description        string `json:"description,omitempty"`
	Invoice            string `json:"invoice,omitempty"`
	Currency           string `json:"currency,omitempty"`
	TypePerson         string `json:"typePerson,omitempty"`
	Country            string `json:"country,omitempty"`
	City               string `json:"city,omitempty"`
	IP                 string `json:"ip,omitempty"`
	URLResponse        string `json:"urlResponse,omitempty"`
	URLConfirmation    string `json:"urlConfirmation,omitempty"`
	MethodConfirmation string `json:"methodConfirmation,omitempty"`
}

CreateChargeParams are the fields accepted to charge a credit card. Send CardNumber/CardExpYear/CardExpMonth/CardCVC/Dues the first time a card is used; ePayco returns CardTokenID/CustomerID in the response so subsequent charges for the same card+customer can omit the raw card data and send CardTokenID/CustomerID instead.

type CreateDaviplataParams

type CreateDaviplataParams struct {
	DocType            string `json:"docType"`
	Document           string `json:"document"`
	Name               string `json:"name"`
	LastName           string `json:"lastName,omitempty"`
	Email              string `json:"email,omitempty"`
	IndCountry         string `json:"indCountry"`
	Phone              string `json:"phone,omitempty"`
	Country            string `json:"country,omitempty"`
	City               string `json:"city"`
	Address            string `json:"address"`
	IP                 string `json:"ip,omitempty"`
	Currency           string `json:"currency,omitempty"`
	Invoice            string `json:"invoice,omitempty"`
	Description        string `json:"description,omitempty"`
	Value              string `json:"value"`
	Tax                string `json:"tax,omitempty"`
	TaxBase            string `json:"taxBase,omitempty"`
	URLResponse        string `json:"urlResponse,omitempty"`
	URLConfirmation    string `json:"urlConfirmation,omitempty"`
	MethodConfirmation string `json:"methodConfirmation"`
}

CreateDaviplataParams are the fields accepted to start a Daviplata transaction. MethodConfirmation is required — confirmed live against the sandbox API ("El campo 'methodConfirmation' es requerido"), even though ePayco's own parameter docs list it as optional. ePayco also enforces an undocumented minimum Value ("monto minimo no superado" was returned for "100" COP; "15000" succeeded).

type CreatePSEParams

type CreatePSEParams struct {
	Bank            string `json:"bank"`
	Value           string `json:"value"`
	DocType         string `json:"docType"`
	DocNumber       string `json:"docNumber"`
	Name            string `json:"name"`
	LastName        string `json:"lastName"`
	Email           string `json:"email"`
	CellPhone       string `json:"cellPhone"`
	IP              string `json:"ip,omitempty"`
	URLResponse     string `json:"urlResponse"`
	URLConfirmation string `json:"urlConfirmation"`
}

CreatePSEParams are the fields required to start a PSE transaction. URLResponse and URLConfirmation are required — confirmed live against the sandbox API ("field urlResponse required"), even though ePayco's own parameter docs list them as optional.

type CreateParams

type CreateParams struct {
	DocType          string `json:"docType"`
	DocNumber        string `json:"docNumber"`
	Name             string `json:"name"`
	LastName         string `json:"lastName"`
	Email            string `json:"email"`
	CellPhone        string `json:"cellPhone"`
	Phone            string `json:"phone"`
	RequireCardToken bool   `json:"requireCardToken"`
	CardTokenID      string `json:"cardTokenId,omitempty"`
	Address          string `json:"address,omitempty"`
	City             string `json:"city,omitempty"`
}

CreateParams are the fields accepted by Create to register a customer and, optionally, attach a previously created card token (see TokenService).

type CreatePlanParams

type CreatePlanParams struct {
	IDPlan                     string  `json:"id_plan"`
	Name                       string  `json:"name"`
	Description                string  `json:"description,omitempty"`
	Amount                     float64 `json:"amount"`
	Currency                   string  `json:"currency"`
	Interval                   string  `json:"interval"`
	IntervalCount              int     `json:"interval_count"`
	TrialDays                  int     `json:"trial_days,omitempty"`
	Tax                        float64 `json:"iva,omitempty"`
	Ico                        float64 `json:"ico,omitempty"`
	PlanLink                   string  `json:"planLink,omitempty"`
	GreetMessage               string  `json:"greetMessage,omitempty"`
	LinkExpirationDate         string  `json:"linkExpirationDate,omitempty"`
	SubscriptionLimit          int     `json:"subscriptionLimit,omitempty"`
	ImgURL                     string  `json:"imgUrl,omitempty"`
	DiscountValue              float64 `json:"discountValue,omitempty"`
	DiscountPercentage         float64 `json:"discountPercentage,omitempty"`
	TransactionalLimit         int     `json:"transactionalLimit,omitempty"`
	AdditionalChargePercentage float64 `json:"additionalChargePercentage,omitempty"`
	FirstPaymentAdditionalCost float64 `json:"firstPaymentAdditionalCost,omitempty"`
}

CreatePlanParams are the fields accepted to create a recurring-billing plan, confirmed against docs/reference/epayco-node/README.md (the official SDKs are the only documented contract for this API).

type CreateSafetypayParams

type CreateSafetypayParams struct {
	Cash               string `json:"cash"`
	ExpirationDate     string `json:"expirationDate"`
	DocType            string `json:"docType"`
	Document           string `json:"document"`
	Name               string `json:"name"`
	LastName           string `json:"lastName"`
	Email              string `json:"email"`
	IndCountry         string `json:"indCountry"`
	Phone              string `json:"phone"`
	Country            string `json:"country"`
	City               string `json:"city"`
	Address            string `json:"address"`
	IP                 string `json:"ip"`
	Currency           string `json:"currency,omitempty"`
	Description        string `json:"description,omitempty"`
	Value              string `json:"value"`
	Tax                string `json:"tax,omitempty"`
	Ico                string `json:"ico,omitempty"`
	TaxBase            string `json:"taxBase,omitempty"`
	URLResponse        string `json:"urlResponse,omitempty"`
	URLConfirmation    string `json:"urlConfirmation,omitempty"`
	MethodConfirmation string `json:"methodConfirmation"`
}

CreateSafetypayParams are the fields accepted to start a Safetypay transaction. Cash is "1" for online banking or "2" for cash payment. City, Address and MethodConfirmation are required — confirmed live against the sandbox API, even though ePayco's own parameter docs list City/Address as optional. ExpirationDate must be no more than 15 days out ("La fecha de expiración no debe superar los 15 dias" for a date further than that).

type CreateStandardParams

type CreateStandardParams struct {
	Channel         string `json:"channel"`
	Value           string `json:"value"`
	DocType         string `json:"docType"`
	DocNumber       string `json:"docNumber"`
	Name            string `json:"name"`
	LastName        string `json:"lastName"`
	Email           string `json:"email"`
	CellPhone       string `json:"cellPhone"`
	Phone           string `json:"phone,omitempty"`
	IP              string `json:"ip,omitempty"`
	City            string `json:"city,omitempty"`
	Address         string `json:"address,omitempty"`
	Description     string `json:"description,omitempty"`
	Invoice         string `json:"_invoice,omitempty"`
	URLResponse     string `json:"urlResponse,omitempty"`
	URLConfirmation string `json:"urlConfirmation,omitempty"`
	// MethodConfimation matches ePayco's own (misspelled) field name exactly
	// as observed in the production Postman collection.
	MethodConfimation string `json:"methodConfimation,omitempty"`
	Extra1            string `json:"extra1,omitempty"`
	Extra2            string `json:"extra2,omitempty"`
	Extra3            string `json:"extra3,omitempty"`
	Extra4            string `json:"extra4,omitempty"`
}

CreateStandardParams are the fields accepted to start a standard checkout transaction.

type CreateSubscriptionParams

type CreateSubscriptionParams struct {
	IDPlan             string `json:"id_plan"`
	Customer           string `json:"customer"`
	TokenCard          string `json:"token_card"`
	DocType            string `json:"doc_type"`
	DocNumber          string `json:"doc_number"`
	URLConfirmation    string `json:"url_confirmation,omitempty"`
	MethodConfirmation string `json:"method_confirmation,omitempty"`
}

CreateSubscriptionParams are the fields accepted to subscribe a customer's card to a plan, confirmed against docs/reference/epayco-node/README.md.

type Customer

type Customer struct {
	Status  bool   `json:"status"`
	Success bool   `json:"success"`
	Type    string `json:"type"`
	Data    struct {
		Status      string `json:"status"`
		Description string `json:"description"`
		CustomerID  string `json:"customerId"`
		Name        string `json:"name"`
		Email       string `json:"email"`
	} `json:"data"`
	Object string `json:"object"`
}

Customer is the customer record returned by Create.

type CustomerCard

type CustomerCard struct {
	Token     string `json:"token"`
	Franchise string `json:"franchise"`
	Mask      string `json:"mask"`
	Created   string `json:"created"`
	Default   bool   `json:"default"`
}

CustomerCard is a card token attached to a customer.

type CustomerDetail

type CustomerDetail struct {
	ID        string         `json:"id_customer"`
	Name      string         `json:"name"`
	Email     string         `json:"email"`
	DocType   string         `json:"doc_type"`
	DocNumber string         `json:"doc_number"`
	Created   string         `json:"created"`
	Cards     []CustomerCard `json:"cards"`
}

CustomerDetail is the full record returned by Get, including attached cards.

type CustomerService

type CustomerService struct {
	// contains filtered or unexported fields
}

CustomerService manages ePayco customers and the card tokens attached to them through the apify API (apify.epayco.co).

func (*CustomerService) AddToken

func (s *CustomerService) AddToken(ctx context.Context, params AddTokenParams) error

AddToken attaches a card token to an existing customer via POST /subscriptions/customer/add/new/token.

func (*CustomerService) Create

func (s *CustomerService) Create(ctx context.Context, params CreateParams) (*Customer, error)

Create registers a customer and/or attaches a card token to it via POST /token/customer.

func (*CustomerService) DeleteToken

func (s *CustomerService) DeleteToken(ctx context.Context, params DeleteTokenParams) error

DeleteToken removes a card token from a customer via POST /subscription/token/card/delete.

func (*CustomerService) Get

func (s *CustomerService) Get(ctx context.Context, customerID string) (*CustomerDetail, error)

Get retrieves a customer and its attached cards via POST /subscriptions/customer.

func (*CustomerService) List

List retrieves every customer registered on the account via GET /subscriptions/customers.

func (*CustomerService) SetDefaultToken

func (s *CustomerService) SetDefaultToken(ctx context.Context, params SetDefaultTokenParams) error

SetDefaultToken makes an existing card the default one for a customer via POST /subscriptions/customer/add/new/token/default.

func (*CustomerService) Update

func (s *CustomerService) Update(ctx context.Context, params UpdateParams) error

Update edits a customer's name via POST /subscriptions/customer/update.

type CustomerSummary

type CustomerSummary struct {
	ID      string `json:"id_customer"`
	Object  string `json:"object"`
	Name    string `json:"name"`
	Email   string `json:"email"`
	Phone   string `json:"phone,omitempty"`
	Created string `json:"created"`
}

CustomerSummary is the summary form of a customer returned by List.

type DaviplataConfirmation

type DaviplataConfirmation struct {
	RefPayco                  string `json:"refPayco"`
	Status                    string `json:"status"`
	Date                      string `json:"date"`
	NumApproval               string `json:"numApproval"`
	IDTransactionDaviplata    int64  `json:"idTransactionDaviplata"`
	IDTransactionAutorization string `json:"idTransactionAutorization"`
	Response                  string `json:"response"`
}

DaviplataConfirmation is the outcome of confirming a Daviplata transaction.

type DaviplataService

type DaviplataService struct {
	// contains filtered or unexported fields
}

DaviplataService creates and confirms Daviplata mobile-wallet transactions through ePayco's apify API.

func (*DaviplataService) Confirm

Confirm completes a Daviplata transaction with the OTP sent to the payer's phone, via POST /payment/confirm/daviplata.

func (*DaviplataService) Create

Create starts a Daviplata transaction via POST /payment/process/daviplata. ePayco sends an OTP to the payer's phone; confirm the payment with Confirm.

type DaviplataTransaction

type DaviplataTransaction struct {
	RefPayco       int
	Invoice        string
	Description    string
	Value          float64
	Tax            float64
	Ico            float64
	TaxBase        float64
	NetoValue      float64
	Currency       string
	Bank           string
	Status         string
	Response       string
	Authorization  string
	Receipt        string
	Date           string
	Franchise      string
	ResponseCode   int
	ErrorCode      string
	IP             string
	TestMode       int
	DocType        string
	Document       string
	Name           string
	LastName       string
	Email          string
	City           string
	Address        string
	IDSessionToken string
}

DaviplataTransaction is the transaction created by Create, pending confirmation with the OTP sent to the payer's phone. Confirmed live against ePayco's sandbox API (2026-07-02): unlike the shape documented in the production Postman collection, the real response has no "transaction" wrapper (the fields are directly under data). Receipt is decoded leniently (see decodeFlexString) for consistency with the same quirk found on Cash and PSE, even though both known examples for this endpoint show it as a bare number.

func (*DaviplataTransaction) UnmarshalJSON

func (d *DaviplataTransaction) UnmarshalJSON(data []byte) error

type DeleteTokenParams

type DeleteTokenParams struct {
	Franchise  string `json:"franchise"`
	Mask       string `json:"mask"`
	CustomerID string `json:"customerId"`
}

DeleteTokenParams identify the card token to remove from a customer.

type Error

type Error struct {
	// Code is the SDK error code (see the ErrCode* constants above). Zero when the
	// error originates from an HTTP response instead of client-side validation.
	Code int
	// Message is a human-readable description of the failure.
	Message string
	// HTTPStatus is the HTTP status code returned by ePayco. Zero for client-side
	// errors that never reached the network (e.g. invalid configuration).
	HTTPStatus int
	// Err is the underlying error, if any (e.g. a network failure).
	Err error
}

Error is the typed error returned by every operation in this SDK.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type NetworkResponse

type NetworkResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

NetworkResponse is the card network's own response code for a charge, nested in ChargeTransaction.

type Option

type Option func(*Client)

Option configures a Client created with New.

func WithApifyBaseURL

func WithApifyBaseURL(url string) Option

WithApifyBaseURL overrides the base URL used for ePayco's unified payments API (login, charges, PSE, cash, Daviplata, Safetypay, standard checkout, card tokenization, customer management, transaction lookup). Defaults to https://apify.epayco.co.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL overrides the legacy core API base URL, used only for Plans and Subscriptions (recurring billing). Defaults to https://api.secure.payco.co.

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient overrides the *http.Client used for every request. Useful for injecting timeouts, custom transports, or test doubles.

func WithLang

func WithLang(lang string) Option

WithLang sets the language ("ES" or "EN") used for error messages returned by the ePayco API. Defaults to "ES".

func WithRetries

func WithRetries(n int) Option

WithRetries sets how many times a request is retried after a transient failure (network error or HTTP 5xx). Defaults to 0 (no retries).

type PSEConfirmation

type PSEConfirmation struct {
	RefPayco      int     `json:"ref_payco"`
	Invoice       string  `json:"factura"`
	Description   string  `json:"descripcion"`
	Value         float64 `json:"valor"`
	Tax           float64 `json:"iva"`
	TaxBase       float64 `json:"baseiva"`
	Currency      string  `json:"moneda"`
	Bank          string  `json:"banco"`
	State         string  `json:"estado"`
	Response      string  `json:"respuesta"`
	Authorization string  `json:"autorizacion"`
	Receipt       string  `json:"recibo"`
	Date          string  `json:"fecha"`
	Franchise     string  `json:"franquicia"`
	DocType       string  `json:"tipo_doc"`
	Document      string  `json:"documento"`
	Names         string  `json:"nombres"`
	LastNames     string  `json:"apellidos"`
	Email         string  `json:"email"`
	City          string  `json:"ciudad"`
	Address       string  `json:"direccion"`
	TransactionID string  `json:"transactionID"`
	TicketID      int64   `json:"ticketId"`
}

PSEConfirmation is the current status of a PSE transaction, returned by Confirm.

type PSEService

type PSEService struct {
	// contains filtered or unexported fields
}

PSEService creates and confirms PSE (Pagos Seguros en Línea) bank-debit transactions through ePayco's apify API.

func (*PSEService) Confirm

func (s *PSEService) Confirm(ctx context.Context, params ConfirmPSEParams) (*PSEConfirmation, error)

Confirm checks whether the bank debit for a PSE transaction went through, via POST /payment/pse/transaction.

func (*PSEService) Create

func (s *PSEService) Create(ctx context.Context, params CreatePSEParams) (*PSETransaction, error)

Create starts a PSE transaction via POST /payment/process/pse. The payer must be redirected to PSETransaction.BankURL to complete the payment.

func (*PSEService) ListBanks

func (s *PSEService) ListBanks(ctx context.Context) ([]Bank, error)

ListBanks retrieves the banks available for PSE via GET /payment/pse/banks.

type PSETransaction

type PSETransaction struct {
	RefPayco      int     `json:"ref_payco"`
	Invoice       string  `json:"factura"`
	Description   string  `json:"descripcion"`
	Value         float64 `json:"valor"`
	Tax           float64 `json:"iva"`
	TaxBase       float64 `json:"baseiva"`
	Currency      string  `json:"moneda"`
	State         string  `json:"estado"`
	Response      string  `json:"respuesta"`
	Authorization string  `json:"autorizacion"`
	Receipt       string  `json:"recibo"`
	Date          string  `json:"fecha"`
	BankURL       string  `json:"urlbanco"`
	TransactionID string  `json:"transactionID"`
	TicketID      string  `json:"ticketId"`
}

PSETransaction is the transaction created by Create, including the bank redirect URL the payer must be sent to.

type PlanService

type PlanService struct {
	// contains filtered or unexported fields
}

PlanService manages recurring-billing plans through ePayco's legacy core API (api.secure.payco.co/recurring/v1). This is the only sanctioned way to manage plans: docs.epayco.com/docs/planes publishes no REST contract for them and directs integrators to the official SDKs instead, which all target this host — see docs/epayco-go-architecture.md section 3.

Unlike the apify resources, no source available (official docs, the production Postman collection, or the reference SDKs themselves) documents a response schema for this API — the reference SDKs just forward whatever ePayco returns. Every method here does the same and returns the decoded JSON as json.RawMessage instead of a fabricated struct; unmarshal it into your own type once you've confirmed the shape against your account.

func (*PlanService) Create

func (s *PlanService) Create(ctx context.Context, params CreatePlanParams) (json.RawMessage, error)

Create registers a recurring-billing plan via POST /recurring/v1/plan/create.

func (*PlanService) Delete

func (s *PlanService) Delete(ctx context.Context, id string) (json.RawMessage, error)

Delete removes a plan via POST /recurring/v1/plan/remove/{apiKey}/{id}.

func (*PlanService) Get

func (s *PlanService) Get(ctx context.Context, id string) (json.RawMessage, error)

Get retrieves a plan by id via GET /recurring/v1/plan/{apiKey}/{id}.

func (*PlanService) List

func (s *PlanService) List(ctx context.Context) (json.RawMessage, error)

List retrieves every plan via GET /recurring/v1/plans/{apiKey}.

func (*PlanService) Update

func (s *PlanService) Update(ctx context.Context, id string, params UpdatePlanParams) (json.RawMessage, error)

Update edits a plan via POST /recurring/v1/plan/edit/{id}.

type SafetypayService

type SafetypayService struct {
	// contains filtered or unexported fields
}

SafetypayService creates Safetypay transactions through ePayco's apify API.

func (*SafetypayService) Create

Create starts a Safetypay transaction via POST /payment/process/safetypay. The payer must be redirected to SafetypayTransaction.BankURL to complete the payment.

type SafetypayTransaction

type SafetypayTransaction struct {
	RefPayco      int
	Invoice       string
	Description   string
	Value         float64
	Tax           float64
	Ico           float64
	TaxBase       float64
	Currency      string
	Status        string
	Response      string
	ResponseCode  string
	ErrorCode     string
	Authorization string
	Receipt       string
	Date          string
	Country       string
	City          string
	BankURL       string
	TransactionID int64
	TicketID      string
}

SafetypayTransaction is the transaction created by Create, including the bank redirect URL the payer must be sent to. Confirmed live against ePayco's sandbox API (2026-07-02): unlike the shape documented in the production Postman collection, the real response has no "transaction" wrapper (the fields are directly under data). Receipt and TicketID are decoded leniently (see decodeFlexString): both came back as quoted strings live, but the Postman-documented example shows TicketID as a bare number.

func (*SafetypayTransaction) UnmarshalJSON

func (s *SafetypayTransaction) UnmarshalJSON(data []byte) error

type SetDefaultTokenParams

type SetDefaultTokenParams struct {
	CardToken  string `json:"cardToken"`
	CustomerID string `json:"customerId"`
	Franchise  string `json:"franchise"`
	Mask       string `json:"mask"`
}

SetDefaultTokenParams identify the card token to promote to default.

type StandardConfirmation

type StandardConfirmation struct {
	RefEpayco         int     `json:"refEpayco"`
	Invoice           string  `json:"invoice"`
	Description       string  `json:"description"`
	Value             float64 `json:"value"`
	Tax               float64 `json:"tax"`
	TaxBase           float64 `json:"taxBase"`
	Currency          string  `json:"currency"`
	Bank              string  `json:"bank"`
	State             string  `json:"state"`
	StateMessage      string  `json:"stateMessage"`
	AuthorizationCode string  `json:"authorizationCode"`
	Receipt           string  `json:"receipt"`
	DateTime          string  `json:"dateTime"`
	Channel           string  `json:"channel"`
	ResponseCode      int     `json:"responseCode"`
	IP                string  `json:"ip"`
	DocType           string  `json:"docType"`
	DocNumber         string  `json:"docNumber"`
	Name              string  `json:"name"`
	LastName          string  `json:"lastName"`
	Email             string  `json:"email"`
	City              string  `json:"city"`
	Address           string  `json:"address"`
}

StandardConfirmation is the confirmed state of a standard checkout transaction, returned by Confirm.

type StandardService

type StandardService struct {
	// contains filtered or unexported fields
}

StandardService creates and confirms "standard checkout" transactions (redirect-based checkout used by ePayco's own hosted-payment products) through ePayco's apify API. Included in v1 at the user's explicit request, even though it has no precedent in the reference SDKs.

func (*StandardService) Confirm

Confirm reports the final outcome of a standard checkout transaction via POST /payment/confirm/standard.

func (*StandardService) Create

Create starts a standard checkout transaction via POST /payment/process/standard.

type StandardTransaction

type StandardTransaction struct {
	RefEpayco         int    `json:"refEpayco"`
	Invoice           string `json:"invoice"`
	Description       string `json:"description"`
	Value             string `json:"value"`
	Tax               string `json:"tax"`
	TaxBase           string `json:"taxBase"`
	Currency          string `json:"currency"`
	Bank              string `json:"bank"`
	State             string `json:"state"`
	StateMessage      string `json:"stateMessage"`
	AuthorizationCode string `json:"authorizationCode"`
	Receipt           string `json:"receipt"`
	DateTime          string `json:"dateTime"`
	Channel           string `json:"channel"`
	ResponseCode      int    `json:"responseCode"`
	IP                string `json:"ip"`
	DocType           string `json:"docType"`
	DocNumber         string `json:"docNumber"`
	Name              string `json:"name"`
	LastName          string `json:"lastName"`
	Email             string `json:"email"`
	City              string `json:"city"`
	Address           string `json:"address"`
	URLRedirect       string `json:"urlRedirect"`
}

StandardTransaction is the transaction created by Create, pending confirmation via Confirm.

type SubscriptionService

type SubscriptionService struct {
	// contains filtered or unexported fields
}

SubscriptionService manages recurring-billing subscriptions through ePayco's legacy core API (api.secure.payco.co/recurring/v1 and /payment/v1). See PlanService's doc comment for why this stays on the legacy API and why responses are returned as json.RawMessage.

func (*SubscriptionService) Cancel

Cancel cancels a subscription via POST /recurring/v1/subscription/cancel.

func (*SubscriptionService) Charge

Charge bills a subscribed customer's card via POST /payment/v1/charge/subscription/create.

func (*SubscriptionService) Create

Create subscribes a customer's card to a plan via POST /recurring/v1/subscription/create.

func (*SubscriptionService) Get

Get retrieves a subscription by id via GET /recurring/v1/subscription/{id}/{apiKey}.

func (*SubscriptionService) List

List retrieves every subscription via GET /recurring/v1/subscriptions/{apiKey}.

type TokenService

type TokenService struct {
	// contains filtered or unexported fields
}

TokenService tokenizes credit cards through ePayco's apify API (apify.epayco.co), so future charges can reference a token instead of raw card data.

func (*TokenService) Create

func (s *TokenService) Create(ctx context.Context, params CreateCardParams) (*CardToken, error)

Create tokenizes a credit card via POST /token/card.

type TransactionDetail

type TransactionDetail struct {
	ClientID            string
	RefPayco            int
	Invoice             string
	Description         string
	Amount              string
	AmountCountry       string
	AmountOk            string
	Tax                 string
	Ico                 int
	BaseTax             string
	Currency            string
	Bank                string
	CardNumber          string
	Quotas              string
	Response            string
	Authorization       string
	TransactionID       string
	Date                string
	CodeResponse        int
	ResponseReasonText  string
	CodTransactionState string
	Status              string
	ErrorCode           string
	Franchise           string
	NameBusiness        string
	DocType             string
	Document            string
	Name                string
	LastName            string
	Email               string
	Phone               string
	IndCountry          string
	Country             string
	City                string
	Address             string
	IP                  string
	Signature           string
	TestMode            string
}

TransactionDetail is the status of a transaction of any payment method, returned by Get. Confirmed live against ePayco's sandbox API (2026-07-02): the real response wraps the record under transaction (not directly under data, as an earlier Postman-documented example showed for a cash lookup). ClientID, Amount, AmountCountry, AmountOk, Tax, BaseTax and CodTransactionState are decoded leniently because ePayco encodes them inconsistently across responses — quoted decimals in some, bare numbers in others (the same quirk found in Bank.Code) — see decodeFlexString.

func (*TransactionDetail) UnmarshalJSON

func (t *TransactionDetail) UnmarshalJSON(data []byte) error

type UpdateParams

type UpdateParams struct {
	CustomerID string `json:"customerId"`
	Name       string `json:"name"`
}

UpdateParams are the fields accepted by Update.

type UpdatePlanParams

type UpdatePlanParams struct {
	Name                       string  `json:"name,omitempty"`
	Description                string  `json:"description,omitempty"`
	Amount                     float64 `json:"amount,omitempty"`
	Currency                   string  `json:"currency,omitempty"`
	Interval                   string  `json:"interval,omitempty"`
	IntervalCount              int     `json:"interval_count,omitempty"`
	TrialDays                  int     `json:"trial_days,omitempty"`
	IP                         string  `json:"ip,omitempty"`
	Tax                        float64 `json:"iva,omitempty"`
	Ico                        float64 `json:"ico,omitempty"`
	TransactionalLimit         int     `json:"transactionalLimit,omitempty"`
	AdditionalChargePercentage float64 `json:"additionalChargePercentage,omitempty"`
	AfterPayment               string  `json:"afterPayment,omitempty"`
}

UpdatePlanParams are the fields accepted to edit an existing plan.

type WebhookPayload

type WebhookPayload struct {
	RefPayco           string
	TransactionID      string
	Response           string
	ResponseReasonText string
	Amount             string
	AmountCountry      string
	AmountOk           string
	Tax                string
	AmountBase         string
	CurrencyCode       string
	ApprovalCode       string
	TransactionDate    string
	TransactionState   string
	Franchise          string
	Description        string
	InvoiceID          string

	CustIDCliente    string
	CustomerDocType  string
	CustomerDocument string
	CustomerName     string
	CustomerLastname string
	CustomerEmail    string
	CustomerPhone    string
	CustomerCountry  string
	CustomerCity     string
	CustomerAddress  string
	CustomerIP       string

	Signature   string
	TestRequest string
	Business    string
	// Extras[0] is x_extra1 ... Extras[9] is x_extra10.
	Extras [10]string
}

WebhookPayload is the data ePayco sends to a merchant's confirmation URL when a transaction's status changes. Field names and the signature formula below are corroborated against docs.epayco.com/docs/url-de-confirmacion and docs.epayco.com/docs/checkout-respuesta-y-confirmacion — no reference SDK implements this (see docs/epayco-go-architecture.md section 8).

func ParseWebhookPayload

func ParseWebhookPayload(r *http.Request) (*WebhookPayload, error)

ParseWebhookPayload extracts a WebhookPayload from an incoming confirmation request. It reads through r.FormValue, which covers both confirmation methods ePayco supports (method_confirmation GET or POST): the URL query string for GET, and the form-encoded body for POST.

Directories

Path Synopsis
examples
charge command
Command charge is a minimal, runnable example of the most common github.com/movaltech/epayco operations: tokenize a card, charge it, look the transaction up by reference, and verify a confirmation webhook.
Command charge is a minimal, runnable example of the most common github.com/movaltech/epayco operations: tokenize a card, charge it, look the transaction up by reference, and verify a confirmation webhook.
testharness command
Command testharness is a throwaway browser-based test bench for github.com/movaltech/epayco: a tiny Go server wraps every apify resource method behind a JSON route, and a single static page (index.html) offers a form per method so you can exercise the real ePayco sandbox by hand and see the raw response — no separate backend project, no JS framework.
Command testharness is a throwaway browser-based test bench for github.com/movaltech/epayco: a tiny Go server wraps every apify resource method behind a JSON route, and a single static page (index.html) offers a form per method so you can exercise the real ePayco sandbox by hand and see the raw response — no separate backend project, no JS framework.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL