Andorpay
Torna al blog

Publicat el · Actualitzat el

SDK per integrar un TPV: abast, API i proves

Què resol un SDK de pagaments i què ha de gestionar el servidor. Connecta comandes, notificacions i aplicació amb una integració clara d’AndorPay.

Peces d’integració connecten un portàtil amb una targeta de pagament.

Un SDK pot simplificar la connexió amb un TPV, però la integració queda completa quan el pagament es relaciona amb la comanda i produeix el resultat correcte a l'aplicació. Per triar-lo, identifica primer què vols connectar: el processament bancari, un checkout allotjat o el sistema que gestiona els cobraments.

Si desenvolupes una web o un servei per a una empresa d'Andorra, aquesta guia t'ajuda a separar la feina de la llibreria de la feina de la teva aplicació. Amb AndorPay pots preparar la connexió per API i utilitzar els esdeveniments de pagament per continuar la venda, sense confondre una petició acceptada amb una comanda pagada.

SDK, API i plugin: què resol cadascun

Una API defineix com es comuniquen dos sistemes. Un SDK agrupa eines per treballar amb un servei des d'un llenguatge o entorn concret. Un plugin connecta aquest servei amb una plataforma, com una botiga, i acostuma a incorporar decisions sobre el seu funcionament.

No són opcions intercanviables. Una aplicació pròpia pot utilitzar una API mitjançant un SDK, mentre que una botiga instal·la un plugin que fa peticions internament. El negoci ha de conèixer el procés final; l'equip tècnic ha de triar una connexió que pugui mantenir.

Les llibreries oficials d'integració de Redsys ajuden amb els paràmetres, les peticions i la signatura. Aquesta ajuda té un abast concret: la teva aplicació encara ha de relacionar l'operació amb la compra i decidir com n'actualitza l'estat.

Comença pel problema que vols resoldre

Si ja fas servir WooCommerce, comprova primer la integració disponible per a la teva instal·lació. Desenvolupar una connexió des de zero pot afegir feina que el plugin ja resol. La nostra guia de WooCommerce explica com AndorPay connecta el pagament amb la comanda.

Si tens una aplicació pròpia, identifica qui crea la compra, quin servidor en conserva la referència i quin esdeveniment permet entregar-la. Amb aquestes dades pots decidir on utilitzar una llibreria. Triar un paquet només perquè s'instal·la ràpid no resol la relació entre els sistemes.

Decideix quin servei vols integrar

Connectar directament un processador i integrar una plataforma que organitza els cobraments són projectes amb responsabilitats diferents. Dibuixa les peces abans de començar: aplicació, servidor, pantalla de pagament, confirmació i sistema que entrega el servei.

En un procés amb AndorPay, el servidor pot crear una sessió de checkout i dirigir el comprador a l'adreça que rep. L'aplicació obté després les notificacions necessàries per continuar. La guia REST documenta aquest contracte; no cal suposar que hi ha un SDK oficial per a cada llenguatge.

Aquesta decisió ha de quedar clara abans de barrejar exemples. Una clau, una signatura o un camp de Redsys no tenen necessàriament el mateix format ni la mateixa funció en una petició a AndorPay. Consulta la documentació del servei al qual fas la crida en cada tram.

Quina feina pot estalviar una llibreria

Una llibreria ajustada al contracte evita repetir codi de comunicació i facilita l'ús dels formats esperats. També pot fer més entenedora la connexió: l'equip sap on es construeix una petició i com se n'interpreta la resposta.

El benefici es veu especialment en el manteniment. Si canvia el format d'un servei, convé localitzar el codi afectat i comprovar l'actualització sense recórrer tota l'aplicació. Concentra la connexió en un mòdul i tradueix els resultats als estats que utilitza el negoci.

Per exemple, la pantalla d'una comanda no hauria de necessitar tots els paràmetres bancaris. Pot mostrar si espera confirmació, si el pagament s'ha completat o si cal alguna acció. El detall tècnic queda disponible per al diagnòstic al component que gestiona la connexió.

Què continua sent responsabilitat del servidor

El servidor ha de relacionar la compra amb el client, el producte i les condicions corresponents. També ha de controlar les dades que accepta del navegador. El comprador pot triar una opció, però l'aplicació ha de comprovar que correspon a una oferta vàlida.

A la integració REST d'AndorPay, la clau d'API és un secret del servidor. No s'inclou al JavaScript públic ni es retorna al comprador. El navegador rep la informació necessària per continuar, com l'adreça de checkout proporcionada pel servei.

Responsabilitat Pregunta que ha de respondre la implementació
Compra Què es contracta i amb quina referència?
Client A quin compte correspon l'operació?
Petició Quin servei i entorn reben les dades?
Confirmació Com es verifica el resultat rebut?
Entrega Quina acció correspon a aquest pagament?
Seguiment On es consulta una operació pendent?

Revisa també els permisos de qui inicia cada acció. Que una crida tingui el format correcte no vol dir que s'hagi d'executar per a qualsevol usuari o comanda. L'aplicació manté aquesta responsabilitat encara que una llibreria construeixi la petició.

La resposta a una petició no acaba la venda

Crear una sessió permet iniciar un procés de pagament. No confirma que el client l'hagi completat. De la mateixa manera, una adreça de retorn permet tornar a la web, però no ha de ser l'única base per marcar la comanda com a pagada.

El comprador pot tancar la finestra després d'autoritzar, perdre la connexió o tornar mentre el resultat encara s'actualitza. El sistema ha de rebre la confirmació i associar-la a la compra independentment del que passi en aquella pantalla.

La documentació del cicle de pagament explica aquesta separació. Fes-la servir per definir els estats visibles a l'aplicació i evitar que un problema de navegació acabi convertit en un segon intent de cobrament.

Prepara les notificacions des del principi

Els webhooks permeten que el servidor rebi esdeveniments sobre el que ha passat. Verifica el missatge segons el contracte documentat abans d'aplicar-ne el contingut. Conserva la relació entre esdeveniment, operació i comanda perquè cada efecte es pugui identificar.

Una notificació repetida s'ha de poder reconèixer. Si el primer missatge ha activat un període de servei, rebre'l un altre cop no hauria d'ampliar-lo de nou. L'aplicació ha de registrar els efectes que ja ha aplicat, encara que el servei torni a entregar el missatge.

Consulta la guia de webhooks d'AndorPay. Separa la verificació de la comunicació de la feina comercial posterior. Així pots investigar un error d'entrega sense tornar a demanar un pagament que ja està confirmat.

Comprova el contracte abans d'automatitzar reintents

Cada servei pot tenir regles diferents per repetir peticions. Una recomanació genèrica sobre idempotència no substitueix la documentació de cada operació. Comprova quines capçaleres accepta i què implica tornar a enviar una sol·licitud.

Concretament, la nostra guia REST indica que POST /v1/checkouts rebutja la capçalera Idempotency-Key. No copiïs un exemple d'un altre proveïdor que l'afegeixi per defecte. Davant una resposta incerta, conserva la referència disponible i comprova l'estat abans de crear una altra acció de cobrament.

També cal distingir repetir una consulta, crear una sessió i executar un càrrec. Són accions amb conseqüències diferents. El tractament d'un error ha de respondre a l'operació concreta, no a una regla que repeteixi tot allò que retorna una fallada.

Com valorar una dependència abans d'afegir-la

Comprova qui publica el paquet i quina documentació en descriu l'abast. Revisa els llenguatges i versions compatibles, el tipus d'integració i el procediment d'actualització. Un nom semblant al del proveïdor no demostra que el component sigui oficial.

Prepara una prova petita a l'entorn adequat i registra la versió utilitzada. Ha de demostrar que pots construir una petició vàlida, interpretar-ne el resultat i resoldre un error conegut. Després connecta el resultat amb una compra de prova de la teva aplicació.

No afegeixis una dependència només per amagar una crida senzilla. Si pots connectar l'API de manera clara amb les eines que ja tens, valora el manteniment addicional del paquet. La decisió útil deixa una connexió entenedora per a qui hagi de resoldre una incidència més endavant.

Proves per revisar el procés complet

Comprova un pagament acceptat, un de rebutjat i un abandonament. Afegeix una notificació repetida i una confirmació que arribi després de tancar el navegador. En tots els casos, compara el resultat del pagament amb l'estat de la comanda o de l'accés.

Utilitza les credencials i els mitjans de prova de l'entorn corresponent. No barregis paràmetres de producció per aconseguir que funcioni una demostració. La guia de proves d'AndorPay descriu els escenaris i els límits dels diferents mètodes.

Abans de publicar, deixa definit qui revisa les incidències i quines referències necessita. Una prova útil també permet explicar una fallada sense buscar claus o dades completes de targeta als registres. El diagnòstic necessita context de l'operació, no informació que l'equip no hauria de guardar.

Preguntes habituals

Un SDK elimina tota la feina d'integració?

Pot simplificar la comunicació amb el servei, però la teva aplicació encara ha de relacionar el pagament amb la compra, verificar els esdeveniments i aplicar-ne el resultat. L'abast concret depèn de l'eina.

Necessito un SDK d'AndorPay per al meu llenguatge?

Pots connectar el backend amb l'API REST documentada. Revisa el contracte i les capacitats necessàries abans de triar una dependència. Si utilitzes una botiga compatible, estudia primer la integració disponible.

Què necessitem per revisar el projecte?

La plataforma, el llenguatge del servidor, el banc i un esquema de la compra. Afegeix si vens productes, serveis o subscripcions i què ha de passar després del pagament. Explica'ns quina integració necessites i concretem la connexió amb tu.

WhatsApp