Skip to main content
POST
/
entities
Create Payment Method
curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityType": "<string>",
  "entityData": {
    "paymentMethod": {
      "type": "<string>",
      "last4": "<string>",
      "brand": "<string>",
      "expiryMonth": "<string>",
      "expiryYear": "<string>",
      "holderName": "<string>",
      "issuerCountry": "<string>",
      "bin": "<string>",
      "fingerprint": "<string>",
      "funding": "<string>",
      "accountNumber": "<string>",
      "accountType": "<string>",
      "bank": "<string>",
      "currency": "<string>",
      "routingNumber": "<string>",
      "provider": "<string>",
      "email": "<string>",
      "address": "<string>",
      "network": "<string>",
      "pixKey": "<string>",
      "pixKeyType": "<string>"
    }
  },
  "relationships": [
    {
      "targetEntityId": "<string>",
      "relationshipType": "<string>",
      "strength": 123,
      "metadata": {}
    }
  ],
  "metadata": {}
}
'
{
  "success": true,
  "id": "<string>",
  "entityType": "<string>",
  "entityData": {},
  "relationships": [
    {}
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

​
Overview

Creates a new payment method entity (credit card, bank account, wallet, etc.) in the system. Payment methods can be linked to person or company entities and used for transaction monitoring and fraud detection.

​
Endpoint

POST http://api.gu1.ai/entities

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
entityType
string
required
Must be "payment_method" for payment method entities
​
entityData
object
required
Container for payment method data
​
relationships
array
Array of relationships to other entities
​
metadata
object
Additional metadata for the payment method entity

​
Example Requests

​
Create Credit Card

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "payment_method",
    "entityData": {
      "paymentMethod": {
        "type": "credit_card",
        "last4": "4242",
        "brand": "visa",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "holderName": "John Doe",
        "issuerCountry": "BR",
        "bin": "424242",
        "funding": "credit"
      }
    },
    "relationships": [
      {
        "targetEntityId": "person-uuid-123",
        "relationshipType": "owns",
        "strength": 1.0
      }
    ]
  }'

​
Create Bank Account

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "payment_method",
    "entityData": {
      "paymentMethod": {
        "type": "bank_account",
        "accountNumber": "12345-6",
        "accountType": "checking",
        "bank": "Banco do Brasil",
        "currency": "BRL",
        "routingNumber": "001",
        "holderName": "John Doe"
      }
    },
    "relationships": [
      {
        "targetEntityId": "person-uuid-123",
        "relationshipType": "owns",
        "strength": 1.0
      }
    ]
  }'

​
Create PIX Payment Method

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "payment_method",
    "entityData": {
      "paymentMethod": {
        "type": "pix",
        "pixKey": "john.doe@example.com",
        "pixKeyType": "email",
        "holderName": "John Doe",
        "currency": "BRL"
      }
    },
    "relationships": [
      {
        "targetEntityId": "person-uuid-123",
        "relationshipType": "owns",
        "strength": 1.0
      }
    ]
  }'

​
Response

​
success
boolean
Whether the operation was successful
​
id
string
UUID of the created payment method entity
​
entityType
string
Always "payment_method"
​
entityData
object
The payment method data as stored
​
relationships
array
Array of relationships created
​
createdAt
string
ISO 8601 timestamp of creation
​
updatedAt
string
ISO 8601 timestamp of last update

​
Response Example

{
  "success": true,
  "id": "payment-method-uuid-123",
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "holderName": "John Doe",
      "issuerCountry": "BR",
      "bin": "424242",
      "funding": "credit"
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ],
  "createdAt": "2024-12-23T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:00:00.000Z"
}

​
Error Responses

​
400 Bad Request

{
  "error": "Invalid entity type or missing required fields",
  "details": {
    "entityType": "Must be 'payment_method'",
    "entityData.paymentMethod.type": "Required field"
  }
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key"
}

​
See Also