Crate kasapay 

One payment API over any payment provider.

Write against Provider and which provider takes the money becomes a deployment decision rather than a rewrite. Five ship with this workspace — Stripe, iyzico, PayTR, Mollie and PayPal — and a provider that lives elsewhere is a first-class one: implement Provider, name it with ProviderId::new. Everything a caller needs is re-exported here; the bundled adapters are behind features, one each.

kasapay = { version = "0.0.5", features = ["stripe", "iyzico"] }

The one thing to understand first

Provider::charge does not mean the money moved. It returns a Charge whose Status is often Status::RequiresAction, with a NextAction saying what the payer must do — confirm in the browser for Stripe, follow a deep link into iyzico’s app for iyzico. Treating a returned Charge as a completed payment is the mistake this crate is shaped to prevent.

What the trait answers

Provider is charge, charge_status, capture, cancel, refund, lookup and instruments, and Capabilities says which of them a given provider actually does — before there is a payment to ask about. A capability that says yes and a call that then fails is a bug in the adapter.

Giving money back is Provider::refund, which answers a Refund with its own life: its own identifier where the provider issues one, its own RefundStatus, and at iyzico’s counter its own NextAction, because there the payer approves the refund in an app. Status has no Refunded and will not grow one — no provider reports a refund as a payment’s status.

The call whose answer never arrived is Provider::lookup, keyed by OrderRef — the caller’s own reference, which they had before they sent anything. Ok(None) means the provider has no record and the charge can safely be sent again. Two of the five can answer it; the rest say what to do instead.

What arrives without being asked for

Webhook is the second trait: it takes the headers and bytes of a Delivery, shows they are the provider’s, and says what they mean as an Event.

use kasapay::{Delivery, EventKind, Webhook};

match verifier.verify(&Delivery::new(headers, body)).await {
    // The identifier goes into a unique index before anything ships: the
    // second delivery of an event must collide rather than ship twice.
    Ok(event) if event.kind == EventKind::Captured => "ship it",
    // Not an error. A provider adding an event type is normal, and
    // refusing one earns days of redeliveries for something nobody wanted.
    Ok(_) => "acknowledged",
    // Do not act on it — and still answer the provider what the provider
    // documents. Those are two different questions.
    Err(_) => "acknowledged",
}

Choosing a provider at runtime

use std::sync::Arc;
use kasapay::{Provider, ProviderId};

match id {
    ProviderId::STRIPE => Some(Arc::new(stripe)),
    ProviderId::IYZICO => Some(Arc::new(iyzico)),
    _ => None,
}

Modules

iyzico

iyzico, behind kasapay’s Provider trait.

kind

What an identifier can name.

mollie

Mollie, behind kasapay’s Provider trait.

paypal

PayPal, behind kasapay’s Provider trait.

paytr

PayTR, behind kasapay’s Provider trait.

stripe

Stripe, behind kasapay’s Provider trait.

Structs

Address

Somewhere to bill, ship or register a payer at.

BasketItem

One line of what is being paid for.

Buyer

The person paying.

Capabilities

What a provider will do, asked before there is a payment to ask it about.

Charge

A charge, as the provider currently sees it.

ChargeRequest

A charge to create.

ChargeRequestBuilder

Collects the parts of a ChargeRequest before it is checked.

Delivery

One delivery from a provider, exactly as it arrived.

Error

A payment operation failed.

Event

What a provider told us happened, once it has been shown to be theirs.

Id

How a provider names one thing of kind K.

IdempotencyKey

A key that makes replaying a charge safe.

Instrument

One instrument a provider holds against a customer.

Money

An amount in one currency, counted in that currency’s minor unit.

OrderRef

Our own reference for an order, chosen by the caller.

ProviderId

Names a provider.

Raw

What a provider actually sent, for everything kasapay does not model.

Refund

Money given back off a payment, as the provider currently sees it.

RefundRequest

A refund to make.

RefundRequestBuilder

Collects the parts of a RefundRequest before it is checked.

RepeatedHeader

A header a signature depends on arrived more than once.

Secret

Holds a credential and keeps it out of Debug output and logs.

UnknownCurrency

The string was not a currency code kasapay supports.

Enums

ChargeRequestError

A ChargeRequest was built out of parts that do not make a valid charge.

Currency

A currency kasapay knows how to move money in.

ErrorKind

What went wrong, in terms a caller can branch on without knowing the provider.

EventKind

What a delivery says happened.

IdSource

Whose uniqueness an identifier rests on.

ItemKind

What kind of thing is being sold.

MoneyError

A decimal string could not be read as an amount in the given currency.

NextAction

What the payer has to do before the payment can go on.

RefundReason

What a merchant tells the provider the money went back for.

RefundRequestError

A RefundRequest was built out of parts that do not make a valid refund.

RefundStatus

Where a refund stands.

Status

Where a payment stands.

Traits

IdKind

What an identifier names — the other question, answered in the type.

Provider

Takes a payment and reports on it.

Webhook

Checks that a delivery is the provider’s, and says what it means.

Type Aliases

EventId

How one delivery to a webhook address is named.

InstrumentId

How the provider names one card it holds, so a payment need not carry one.

PaymentId

How the provider names a payment.

RefundId

How the provider names one refund, where it names it at all.

Attribute Macros

async_trait