Vai al contenuto principale
Crea o aggiorna una sessione di pagamento per un ordine Pending. L’azione di pagamento accederà al canale di pagamento e potrebbe modificare lo stato dell’ordine; prima della chiamata è necessario confermare l’ID dell’ordine, l’importo e il metodo di pagamento.

Panoramica dell’interfaccia

Limiti del pagamento anonimo

L’accesso anonimo è destinato allo scenario in cui la sessione di accesso viene persa dopo l’apertura di un link di pagamento copiato, non richiede né deve includere un Account Token a lungo termine. Le chiamate anonime:
  • consentono solo i metodi di pagamento con reindirizzamento gestito configurati dal server;
  • utilizzano sempre la pagina di pagamento desktop;
  • non possono riscuotere ordini a costo zero;
  • sono soggette a limitazione della frequenza per IP e per singolo ordine;
  • restituiscono una proiezione minima dell’ordine, senza account, Application o metadata interni.
I chiamanti autenticati devono essere il proprietario dell’ordine o un super amministratore. Metodi che richiedono il contesto utente, come X402 e il riscatto delle ricompense, non possono essere chiamati in modo anonimo.

Esempi di richiesta

Metodi di pagamento che richiedono autenticazione:
pay_way utilizza i valori reali supportati dal modello dell’ordine, ad esempio WechatPay, AliPay, Stripe, Card, Airwallex, X402, PayPal, AppleIAP, Reward, BankTransfer. Non tutti i valori sono disponibili per richieste anonime o per ogni sito.

Descrizione della risposta

La risposta di successo è l’oggetto ordine aggiornato, che solitamente fornisce il punto di accesso al passaggio successivo tramite pay_url; diversi metodi di pagamento possono inoltre restituire, in campi controllati, le informazioni necessarie al client per continuare il pagamento. Le risposte anonime utilizzano una whitelist minima di campi, mentre il proprietario autenticato riceve i dettagli completi. Non fare affidamento su vecchi nomi di campo come payment_url, qr_code_url o payment_method; l’attuale contratto Order utilizza pay_url e pay_way.

Bonifico bancario

Sia gli account personali sia gli account aziendali autenticati possono utilizzare BankTransfer, senza necessità di autenticazione aziendale. Sia i bonifici in RMB nazionali sia i bonifici internazionali in USD richiedono che l’importo dell’ordine sia di almeno 300 USD; l’importo dovuto in RMB è quello visualizzato al momento del pagamento. Prima del pagamento, è possibile interrogare le rotte di bonifico disponibili e le soglie di importo per l’ordine corrente tramite GET /api/v1/orders/{order_id}/payment-options/. I bonifici bancari devono essere avviati dopo l’accesso dal proprietario dell’ordine e sono soggetti alla configurazione del canale di incasso e all’ambito di applicabilità del piano; le richieste anonime non possono utilizzarli.

Acquisti in-app iOS

Il proprietario dell’ordine autenticato può passare pay_way: "AppleIAP". Questa richiesta aggiorna l’ordine in attesa di pagamento in base a metadata.apple_price del piano selezionato e rimuove lo sconto; non genera alcun addebito, non eroga crediti e non restituisce un link di pagamento. I vecchi ordini in attesa di pagamento devono prima completare questo passaggio, quindi avviare il pagamento nativo Apple. È supportato solo un piano Usage con prodotto e prezzo Apple configurati; i piani non supportati o gli ordini in blocco restituiscono 400. Dopo il pagamento nativo Apple, invia transaction_id tramite /api/v1/orders/{id}/apple-verify/ per completare la verifica lato server e l’erogazione dei crediti. La quantità di crediti deriva dal piano; l’importo utilizza il prezzo preimpostato in USD separato di Apple, senza cumulare sconti membri o maggiorazioni del sito, e l’importo dell’addebito in valuta locale per le altre regioni è quello indicato nella pagina di conferma Apple.

Errori e tentativi

  • L’ordine non è Pending: restituisce 400; non creare ripetutamente sessioni di pagamento.
  • pay_way non fornito: gli ordini con importo diverso da zero restituiscono 400.
  • Una chiamata anonima utilizza un metodo non consentito o un ordine a costo zero: restituisce 403, riprova dopo l’accesso come proprietario.
  • Autenticato ma non proprietario dell’ordine: restituisce 403.
  • Il canale di pagamento non riesce: non inviare nuovamente alla cieca; prima consulta i dettagli dell’ordine, conferma che sia ancora Pending e poi riprova.

Interfacce correlate