PagosRápidos SL — Shopify Payments Apps API Integration

1 Iniciar Sesión de Pago

mutation

# Crear sesión al iniciar checkout
# Docs: shopify.dev/docs/api/payments-apps
mutation PaymentSessionCreate($id: ID!) {
  paymentSessionCreate(id: $id) {
    paymentSession {
      id
      state {
        ... on PaymentSessionStatePending {
          reason
        }
      }
      nextAction {
        action
        context {
          ... on PaymentSessionActionsRedirect {
            redirectUrl
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

# Variables:
# { "id": "gid://shopify/PaymentSession/abc123" }

2 Aprobar Pago (Post-3DS)

mutation

# Confirmar tras auth 3DS exitosa
# Triggers: Bizum callback / card auth
mutation PaymentSessionApprove(
  $id: ID!
) {
  paymentSessionApprove(id: $id) {
    paymentSession {
      id
      state {
        ... on PaymentSessionStateApproved {
          reason
        }
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

# Variables:
# { "id": "gid://shopify/PaymentSession/abc123" }
# Llamar desde webhook de PagosRápidos SL

3 Rechazar / Declinar Pago

mutation

# Pago denegado por banco o fraude
mutation PaymentSessionReject(
  $id: ID!
  $reason: PaymentSessionRejectionReasonInput!
) {
  paymentSessionReject(
    id: $id
    reason: $reason
  ) {
    paymentSession {
      id
      state {
        ... on PaymentSessionStateRejected {
          reason
          reasonMessage
        }
      }
    }
    userErrors { field message }
  }
}

# Variables:
# { "id": "gid://shopify/PaymentSession/abc",
#   "reason": { "code": "RISKY",
#     "merchantMessage": "Fondos insuficientes" }}

4 Iniciar Devolución (Refund)

mutation

# Resolver sesión de refund completo/parcial
mutation RefundSessionResolve($id: ID!) {
  refundSessionResolve(id: $id) {
    refundSession {
      id
      state {
        ... on RefundSessionStateSuccess {
          code
        }
        ... on RefundSessionStateFailed {
          code
          merchantMessage
        }
      }
    }
    userErrors { field message }
  }
}

# PagosRápidos recibe webhook de Shopify
# con refundSession.id, procesa devolución
# y llama este mutation como confirmación

5 Cancelar Pago No Capturado (Void) + Webhook Handler Node.js

mutation · backend

# GraphQL: Void session
mutation VoidSessionResolve($id: ID!) {
  voidSessionResolve(id: $id) {
    voidSession {
      id
      state {
        ... on VoidSessionStateSuccess {
          code
        }
        ... on VoidSessionStateFailed {
          code
          merchantMessage
        }
      }
    }
    userErrors { field message }
  }
}
// Node.js: Shopify webhook handler
import { shopifyApi } from '@shopify/shopify-api';

export async function handleVoidWebhook(req, res) {
  const { id, payment_id, amount } = req.body;

  // 1. Cancelar en PagosRápidos SL
  await pagosRapidos.cancelAuthorization(payment_id);

  // 2. Confirmar a Shopify via GraphQL
  const client = new shopifyApi.clients.Graphql({
    session: shopSession
  });

  await client.query({
    data: {
      query: VOID_SESSION_RESOLVE,
      variables: { id }
    }
  });

  res.status(200).json({ ok: true });
}

Pago Aprobado — paymentSessionApprove

{
  "data": {
    "paymentSessionApprove": {
      "paymentSession": {
        "id": "gid://shopify/PaymentSession/abc123",
        "state": {
          "reason": null
        }
      },
      "userErrors": []
    }
  }
}
// Estado: PaymentSessionStateApproved
// Bizum: referencia PR-2024-78923

Pago Rechazado — paymentSessionReject

{
  "data": {
    "paymentSessionReject": {
      "paymentSession": {
        "id": "gid://shopify/PaymentSession/xyz789",
        "state": {
          "reason": "RISKY",
          "reasonMessage": "Fondos insuficientes"
        }
      },
      "userErrors": []
    }
  }
}
// Estado: PaymentSessionStateRejected
// Sequra: error code SEQ_403

Método	Mutation Principal	3DS	Refund	Void	Estado
Bizum	paymentSessionCreate	Redirect	✓ Parcial	✓	Live
Tarjeta Débito/Crédito	paymentSessionCreate	3DS v2.2	✓ Parcial	✓	Live
Sequra (Financiación)	paymentSessionCreate	No aplica	Solo total	✓	Beta

PagosRápidos SL — Shopify Integration