torobpay

Documentation

Overview

Package torobpay implements the TorobPay online credit gateway (REST, api.torobpay.com).

TorobPay is Torob's buy-now-pay-later product: the payer settles the invoice in four instalments and the merchant is paid in full. The API is shaped like an OAuth protected REST service — a payment token, a hosted page, then a verification — with reversal and cancellation as separate calls.

Credentials: core.Config.Username and core.Config.Password are the merchant user of the OAuth password grant, while core.Config.MerchantID and core.Config.MerchantKey are the OAuth client id and client secret.

Index

• Constants
• func WithCart(carts ...Cart) core.Option
• func WithCartBuilder(builder CartBuilder) core.Option
• func WithDefaultCategory(category string) core.Option
• func WithPaymentMethod(method string) core.Option
• func WithSettle(enabled bool) core.Option
• type Cart
• type CartBuilder
• type CartItem
• type Gateway
  • func New(cfg core.Config, opts ...core.Option) (*Gateway, error)
  • func (g *Gateway) Cancel(ctx context.Context, paymentToken string) error
  • func (g *Gateway) Capabilities() core.Capabilities
  • func (g *Gateway) Inquiry(ctx context.Context, req core.InquiryRequest) (core.InquiryResponse, error)
  • func (g *Gateway) Name() core.Name
  • func (g *Gateway) ParseCallback(r *http.Request) (core.Callback, error)
  • func (g *Gateway) Purchase(ctx context.Context, req core.PurchaseRequest) (core.PurchaseResponse, error)
  • func (g *Gateway) Refund(ctx context.Context, req core.RefundRequest) (core.RefundResponse, error)
  • func (g *Gateway) Verify(ctx context.Context, req core.VerifyRequest) (core.VerifyResponse, error)

Constants

const Name core.Name = "torobpay"

Name is the registry name of this gateway.

Functions

func WithCart

func WithCart(carts ...Cart) core.Option

WithCart sends a fixed basket with every purchase.

func WithCartBuilder

func WithCartBuilder(builder CartBuilder) core.Option

WithCartBuilder installs the function that turns a purchase request into the baskets TorobPay is shown.

func WithDefaultCategory

func WithDefaultCategory(category string) core.Option

WithDefaultCategory sets the product category the default cart builder uses.

func WithPaymentMethod

func WithPaymentMethod(method string) core.Option

WithPaymentMethod overrides the TorobPay payment method type, for contracts that sell a product other than the default ONLINE_CREDIT one.

func WithSettle

func WithSettle(enabled bool) core.Option

WithSettle makes core.Gateway.Verify follow the verification with the settlement call.

It is off by default because this package has always treated verification as the end of the TorobPay flow. Turn it on if your contract says otherwise — SnappPay, which serves the same endpoint paths, reverts any payment that is verified and never settled, and a payment lost that way is not recoverable from the merchant's side. Ask TorobPay which of the two your terminal follows rather than guessing from the behaviour of a test payment, since the reversal only shows up once the settlement window closes.

Types

type Cart

type Cart struct {
	// CartID identifies the basket inside the order.
	CartID string `json:"cartId"`
	// TotalAmount is the basket total in Rial.
	TotalAmount int64 `json:"totalAmount"`
	// TaxAmount is the tax in Rial.
	TaxAmount int64 `json:"tax_amount"`
	// ShippingAmount is the delivery cost in Rial.
	ShippingAmount int64 `json:"shipping_amount"`
	// IsTaxIncluded reports whether TaxAmount is already part of TotalAmount.
	IsTaxIncluded bool `json:"is_tax_included"`
	// IsShipmentIncluded reports whether ShippingAmount is already part of
	// TotalAmount.
	IsShipmentIncluded bool `json:"is_shipment_included"`
	// CartItems are the lines of the basket.
	CartItems []CartItem `json:"cartItems"`
}

Cart is one basket sent with a payment. TorobPay lends against the goods, so it wants the basket contents; a purchase without one is refused.

The field names follow TorobPay's own mixed spelling, which differs from the otherwise similar SnappPay contract.

type CartBuilder

type CartBuilder func(req core.PurchaseRequest) []Cart

CartBuilder turns a purchase request into the baskets sent to TorobPay. Set one with WithCartBuilder when the real basket lines matter; the default builder sends a single line covering the whole order.

type CartItem

type CartItem struct {
	// ID is the merchant side product identifier.
	ID string `json:"id"`
	// Name is the product name shown to the payer.
	Name string `json:"name"`
	// Count is the quantity.
	Count int `json:"count"`
	// Amount is the unit price in Rial.
	Amount int64 `json:"amount"`
	// Category is the merchant's product category.
	Category string `json:"category"`
	// CommissionType is the commission group agreed with TorobPay. The field
	// keeps the provider's own spelling.
	CommissionType int `json:"comission_type,omitempty"`
}

CartItem is one line of a Cart.

type Gateway

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

Gateway is the TorobPay implementation of core.Gateway.

func New

func New(cfg core.Config, opts ...core.Option) (*Gateway, error)

New builds a TorobPay gateway.

func (*Gateway) Cancel

func (g *Gateway) Cancel(ctx context.Context, paymentToken string) error

Cancel drops a payment the payer never completed, freeing the credit TorobPay reserved for it.

func (*Gateway) Capabilities

func (g *Gateway) Capabilities() core.Capabilities

Capabilities reports what TorobPay offers.

func (*Gateway) Inquiry

func (g *Gateway) Inquiry(ctx context.Context, req core.InquiryRequest) (core.InquiryResponse, error)

Inquiry reads the current state of a payment, which is how a lost callback is recovered from.

func (*Gateway) Name

func (g *Gateway) Name() core.Name

Name returns the gateway name.

func (*Gateway) ParseCallback

func (g *Gateway) ParseCallback(r *http.Request) (core.Callback, error)

ParseCallback reads the parameters TorobPay returns the payer with. The payment is only final once Gateway.Verify succeeded.

func (*Gateway) Purchase

func (g *Gateway) Purchase(ctx context.Context, req core.PurchaseRequest) (core.PurchaseResponse, error)

Purchase creates a credit payment and returns the TorobPay page the payer is sent to.

func (*Gateway) Refund

func (g *Gateway) Refund(ctx context.Context, req core.RefundRequest) (core.RefundResponse, error)

Refund reverts a verified payment, cancelling the payer's instalment plan.

func (*Gateway) Verify

func (g *Gateway) Verify(ctx context.Context, req core.VerifyRequest) (core.VerifyResponse, error)

Verify confirms a completed payment.

Whether that is the end of the flow depends on the contract: this package assumes TorobPay settles the credit itself, which is how the gateway has always behaved here. Its sibling SnappPay serves the same endpoint paths and does require a separate settle call, reverting anything left unsettled, so confirm which of the two your contract follows and turn WithSettle on if TorobPay expects the second call. Settling a payment that needs no settling is an error from the provider; not settling one that does is a payment the merchant never receives.